Tightened up the profiles specification

docs/hsds/profiles.md

@@ -6,29 +6,41 @@ Profiles Reference
 
 As an international standard, HSDS provides a common core of defintions and objects for describing health, human, and social services as well as their locations and the organizations that provide them. This allows HSDS to acommodate a wide range of applications and provide value in a variety of use cases.
 
-Being an international standard, however, means that the needs of HSDS publishers and users are often significantly variable across varying contexts. In different geographies, sectors, and scenarios of usage, users may need different information about services, locations, and organizations.
+Being an international standard, however, means that the needs of HSDS publishers and users are often significantly variable across varying contexts. In different geographies, sectors, and scenarios of usage, users MAY need different information about services, locations, and organizations.
 
 To this end, HSDS provides the following **Profiles Specification**. HSDS Profiles can be specified as a series of changes from the HSDS Specification to address specific or local contexts.
 
 As per the [Conformance](conformance) section, a publication is considered conformant to HSDS if it is conformant to a valid HSDS Profile as specified in this reference.
 
 ## Profiles Specification
 
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+### Profile URLs
+
+Profiles MUST provide a canonical URI ([RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)) which resolves to a canonical resource describing the Profile.
+
+When implementing modifications to the [HSDS API Specification file](https://github.com/openreferral/specification/blob/3.0/schema/openapi.json), Profiles SHOULD specify that the response object to the `/` API endpoint includes this URI as the value of the `profile` property. This is so that HSDS publications can declare the Profile they are conformant to.
+
 ### Specification format
 
-Profile specifications must be implemented as a set of files which describe modifications to existing HSDS specification files.
+Profile specifications MUST be implemented as a set of files which describe modifications to existing HSDS specification files as defined at the following canonical URL: [https://github.com/openreferral/specification/tree/3.0/schema](https://github.com/openreferral/specification/tree/3.0/schema). 
+
+In the case of object schemas (e.g. `service.json`, `organization.json`, `phone.json`, etc.), modifications MUST be implemented so that they produce valid JSON Schema — i.e. conformant with the [JSON Schema Draft 2020-12 Core/Validation metaschema](https://json-schema.org/specification-links.html#2020-12) — when merged with the corresponding schema defining an object in HSDS by means of a JSON Merge Patch ([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386)). A modification MUST be implemented in a file with the same filename as the corresponding schema in HSDS which it is intended to modify.
 
-In the case of object schemas (e.g. `service.json`, `organization.json`, `phone.json`, etc.), modifications must be implemented so that they produce valid JSON Schema — i.e. conformant with the [JSON Schema Draft 2020-12 Core/Validation metaschema](https://json-schema.org/specification-links.html#2020-12) — when merged with the corresponding schema defining an object in HSDS by means of a JSON Merge Patch ([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386)). For example, a Profile describing a modification to HSDS' [service definition file](https://github.com/openreferral/specification/blob/3.0/schema/service.json) must produce valid JSON Schema when merged with this file via a process conforming to RFC 7386.
+For example, a Profile describing a modification to HSDS' [service definition file](https://github.com/openreferral/specification/blob/3.0/schema/service.json) MUST be named `profile.json` and MUST produce valid JSON Schema when merged with this file via a process conforming to RFC 7386.
 
-In the case of the API specification file (`openapi.json`), modifications must be implemented so that the result of merging them with [the HSDS OpenAPI specification file](https://github.com/openreferral/specification/blob/3.0/schema/openapi.json) produces a result that is conformant to the [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/latest.html#version-3-1-0).
+In the case of the API specification file (`openapi.json`), modifications MUST be implemented so that the result of merging them with [the HSDS OpenAPI specification file](https://github.com/openreferral/specification/blob/3.0/schema/openapi.json) produces a result that is conformant to the [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/latest.html#version-3-1-0). As with the modifications to schema files, the modification to the API specification file MUST be named to correspond with the API specification in HSDS (currently `openapi.json`).
+
+Profile specifications MUST make these files available via publically accessible URIs which return the files. Profiles SHOULD implement the modifications under a `/profile` endpoint accessible underneath their canonical URI as described in the previous section. This MAY be implemented so that the URI is a result of a directory structure or it MAY be a logical endpoint. Given the prevalence of large-scale public code repositories such as Github and Gitlab.com, Profiles MAY store the modifications inside a `/profile` directory of their repository and use the public URI for the repository as their canonical URI. In this event, tools SHOULD transform the canonical URI so that the raw files MAY be retrieved. For example a Profile with the canonical URI `https://github.com/openreferral/hsds_example_profile` MAY provide its modifications to `service.json` under the following URI: `https://raw.githubusercontent.com/openreferral/hsds_example_profile/main/profile/service.json` while the modifications to `openapi.json` would be available under: `https://raw.githubusercontent.com/openreferral/hsds_example_profile/main/profile/openapi.json` in the same implementation.
 
 ### Profile Versioning
 
-Profiles may choose any versioning scheme that is deemed suitable, but it is recommended to use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Profiles MAY choose any versioning scheme that is deemed suitable, but it is recommended to use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-Profiles should be versioned independently of HSDS. For example if *Profile A* is derived from [HSDS 3.0](https://github.com/openreferral/specification/releases/tag/v3.0) then the *Profile A* must not be said to be *Profile A 3.0* unless its own version increments to `3.0` through its own upgrade and governance processes.
+Profiles SHOULD be versioned independently of HSDS. For example if *Profile A* is derived from [HSDS 3.0](https://github.com/openreferral/specification/releases/tag/v3.0) then the *Profile A* SHOULD NOT be said to be *Profile A 3.0* unless its own version increments to `3.0` through its own upgrade and governance processes.
 
-Profiles should adapt to upgrades in HSDS, which may be considered as 'upstream' for these purposes, however they may also choose to ignore these upgrades. When a Profile adapts to changes in HSDS, it should update its own version number according to its versioning and governance processes.
+Profiles SHOULD adapt to upgrades in HSDS, which MAY be considered as 'upstream' for these purposes, however they MAY also choose to ignore these upgrades. When a Profile adapts to changes in HSDS, it SHOULD update its own version number according to its versioning and governance processes.
 
 ```{admonition} Worked Example:
 
@@ -39,19 +51,13 @@ Profiles should adapt to upgrades in HSDS, which may be considered as 'upstream'
 
 ```
 
-### Profile URLs
-
-Profiles must provide a URI ([RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)) which resolves to a canonical resource giving information about the Profile.
-
-When implementing modifications to the [HSDS API Specification file](https://github.com/openreferral/specification/blob/3.0/schema/openapi.json), Profiles should specify that the response object to the `/` API endpoint includes this URI as the value of the `profile` property.
-
 ### Permitted Modifications
 
-Profiles are permitted a generous set of operations against the HSDS Specification which enables them to both extend and override it. Overriding may include changing the way properties or validation rules behave or removing them entirely.
+Profiles are permitted a generous set of operations against the HSDS Specification which enables them to both extend and override it. Overriding MAY include changing the way properties or validation rules behave or removing them entirely.
 
 #### Extending the HSDS Specification
 
-A Profile may:
+A Profile MAY:
 
 * Add new optional or required properties to its specification.
 * Add new validation rules to its specification, including making existing HSDS properties 'required' and stipulating patterns or formats for conformance on existing HSDS properties.
@@ -61,7 +67,7 @@ A Profile may:
 
 #### Overriding the HSDS Specification
 
-A Profile may:
+A Profile MAY:
 
 * remove properties and their validation rules from the HSDS specifications by overriding their definitions with `null`.
 * remove entire objects from the HSDS Specification by overriding its object schema with `null`.
@@ -70,9 +76,9 @@ A Profile may:
 
 ### Serializing to Tabular Data Packages
 
-Profiles should support serialization to a [Tabular Data Package](https://specs.frictionlessdata.io/tabular-data-package/#specification) format.
+Profiles SHOULD support serialization to a [Tabular Data Package](https://specs.frictionlessdata.io/tabular-data-package/#specification) format.
 
-This should be done by providing a `datapackage.json` file conformant to the [Frictionless Tabular Data Package schema](https://specs.frictionlessdata.io/schemas/tabular-data-package.json), which describes the serialization of the Profile accurately.
+This SHOULD be done by providing a `datapackage.json` file conformant to the [Frictionless Tabular Data Package schema](https://specs.frictionlessdata.io/schemas/tabular-data-package.json), which describes the serialization of the Profile accurately. Profiles MAY choose to implement this separately, but it is RECOMMENDED that Profiles generate this from schema files which result from compiling their modifications with the HSDS specification files via the JSON Merge patch.
 
 ## Reference Implementation