Further tightened the Profile specification

docs/hsds/identifiers.md

@@ -11,15 +11,19 @@ HSDS stipulates that the values in all `id` properties must conform to the *Univ
 
 A number of tools exist to support publishers generating UUIDs:
 
-* [Online UUID Generator](https://www.uuidgenerator.net/) (web)
-* [uuidgen](https://www.man7.org/linux/man-pages/man1/uuidgen.1.html) is available in the repos of many GNU/Linux and BSD systems (CLI)
-* UUID support was added to MySQL in [version 8.0](https://dev.mysql.com/blog-archive/mysql-8-0-uuid-support/) (database software)
-* PostgreSQL provides [UUID functions](https://www.postgresql.org/docs/current/functions-uuid.html) (database software)
-* MongoDB provides a [UUID function](https://www.mongodb.com/docs/manual/reference/method/UUID/) (database software)
-* [libuuid](https://sourceforge.net/projects/libuuid/files/) is a portable library for C to generate UUIDs (programming library)
-* Python3 provides a [uuid object](https://docs.python.org/3/library/uuid.html) (programming library)
-* There is a [uuid Crate](https://docs.rs/uuid/latest/uuid/#) available for Rust (programming library)
-* There is a [uuid package](https://www.npmjs.com/package/uuid) available for NodeJS via npm (programming library)
+* Web Tools
+  * [Online UUID Generator](https://www.uuidgenerator.net/)
+* CLI or Desktop Tools
+  * [uuidgen](https://www.man7.org/linux/man-pages/man1/uuidgen.1.html) is available in the repos of many GNU/Linux and BSD systems
+* Database Tools
+  * UUID support was added to MySQL in [version 8.0](https://dev.mysql.com/blog-archive/mysql-8-0-uuid-support/) 
+  * PostgreSQL provides [UUID functions](https://www.postgresql.org/docs/current/functions-uuid.html) 
+  * MongoDB provides a [UUID function](https://www.mongodb.com/docs/manual/reference/method/UUID/) 
+* Programming Libraries
+  * [libuuid](https://sourceforge.net/projects/libuuid/files/) is a portable library for C to generate UUIDs 
+  * Python3 provides a [uuid object](https://docs.python.org/3/library/uuid.html) 
+  * There is a [uuid Crate](https://docs.rs/uuid/latest/uuid/#) available for Rust 
+  * There is a [uuid package](https://www.npmjs.com/package/uuid) available for NodeJS via npm 
 
 There are likely many more suitable for your needs.
 

docs/hsds/profiles.md

@@ -18,25 +18,30 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 ### 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.
+Profiles MUST provide a 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 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). 
+Profile specifications MUST be implemented as a set of files which describe modifications to existing HSDS specification files as defined in files available in the HSDS schema directory 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.
 
-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.
+For example, a Profile describing a modification to HSDS' [service definition file](https://github.com/openreferral/specification/blob/3.0/schema/service.json) MUST define these modifications in a file named `service.json`. When merging this with HSDS' canonical [service.json file](https://raw.githubusercontent.com/openreferral/specification/3.0/schema/service.json) via a process conforming to RFC 7386, the result MUST be a valid JSON Schema which validates against the JSON Schema Draft 2020-12 Core/Validation metaschema defined at: [http://json-schema.org/draft/2020-12/schema](http://json-schema.org/draft/2020-12/schema).
 
 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 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. In addition, Profiles SHOULD pre-generate full Profile schemas by performing the JSON Merge Patch process using their defined modifications and retrieving copies of the canonical HSDS schemas, and make these available under a `/schema` endpoint accessible underneath their canonical URI. In both cases the `/profile` and `/schema` endpoints  MAY each be implemented so that the URI is a result of a directory structure or it MAY be a logical endpoint defined by configuring a web server or a web framework.
+
+The motivation for providing pre-generated schema files is to support tooling retrieving these for conformance checks against the Profile. However, tooling MAY be configured to retrieve the modifications and perform the JSON Merge patch itself. Tooling MAY perform both operations to compare results, and if the results are in conflict then the results derived from the Profile schemas MUST take precedence.
+
+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 can 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. Given this, Profiles MAY store the generated schemas inside a `/schema` directory of the repository. The the compiled versions of these files would be available under the following URIs: `https://raw.githubusercontent.com/openreferral/hsds_example_profile/main/profile/service.json` for the `service.json` representing the Profile's specification for a service and `https://raw.githubusercontent.com/openreferral/hsds_example_profile/main/schema/openapi.json` for `openapi.json` representing the Profile's API Specification.
+
 
 ### 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* 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.