Merge branch '3.2' into greggish-patch-1

mrshll1001 · web-flow · commit 8ffb70633320 · 2025-12-04T16:00:30.000Z
diff --git a/docs/about/credits.md b/docs/about/credits.md
@@ -3,6 +3,8 @@ Credits
 
 The Open Referral Initiative is led by Greg Bloom ([@greggish](https://github.com/greggish)). Its launch in 2014 was co-sponsored by [Code for America](http://codeforamerica.org), with funding from [the Knight Foundation](https://knightfoundation.org). 
 
+Project documentation for Open Referral, along with open source collateral work materials, can be accessed in ([this public file folder](https://drive.google.com/drive/folders/0B-5CZ4ZLjTHqfk12WTFUbVk1NjBYMjRaZTlZRlN1UjhWMS1MN0tLV3Q4ejY3TWpOYWwwVDg?resourcekey=0-V8QRlJu4Jlrw40yN1U_TKQ&usp=sharing)). 
+
 The Human Services Data Specification is developed under the technical stewardship of [the Open Data Services Cooperative](http://opendataservices.coop/) (read more [here](https://openreferral.org/meet-the-open-data-services-cooperative/)). 
 
 Open Referral's [Explainer Video](https://www.youtube.com/watch?v=yHsIZhACSVc) was made possible by a small grant from [the Shuttleworth Foundation](http://shuttleworthfoundation.org/).
diff --git a/docs/about/specification-governance.md b/docs/about/specification-governance.md
@@ -35,10 +35,6 @@ The committee consists of people with a track record of contributing input to th
 
 The committee also can advise Open Referral’s Lead Organizer on issues related to the Open Referral community at large, and can make recommendations as to investments in development of tools and other tech that can support adoption and use of HSDS.
 
-#### As of Spring 2024, the Open Referral Technical Committee is in formation
-
-Upon formation of this body, the body will manage itself – beginning by writing a charter that establishes: how people are added/removed, how decisions will be made, how the body can be dissolved, etc. This can be authored by the founding members and reviewed by the technical steward, and must be approved by the lead organizer and fiscal sponsor. 
-
 ### The process for requesting changes to HSDS is open to anyone.
 
 Input on Open Referral's specifications and materials can be shared through several channels: our [Github queue](https://github.com/openreferral/specification/issues), our [Community Forum](https://forum.openreferral.org/), and occasional community Assemblies. The Technical Steward is responsible for receiving and synthesizing such input from across channels for review by the Technical Committee. The Technical Committee members are empowered to propose specific changes to the specifications; proposed changes that are met with rough consensus (i.e. most support and nobody objects) are acknowledged in the Forum advanced to the Technical Steward for codification. Upon receiving all outputs from the Technical Committee, the Technical Steward develops a fully specified proposal for a version upgrade, which is shared with the community for a Request for Comment period (usually of about two weeks). The Technical Steward receives any additional input through this period, and can call for additional meetings of the Technical Committee to seek consensus on additional changes as necessary.
diff --git a/docs/extras/openapi30.json b/docs/extras/openapi30.json
@@ -9,12 +9,33 @@
       "url": "https://creativecommons.org/licenses/by/4.0/"
     }
   },
+  "tags": [
+    {
+      "name": "required",
+      "description": "This endpoint is REQUIRED by the HSDS API Specification",
+      "externalDocs": {
+        "description": "This URI points to the codelist file used to define the codes in HSDS which are then used to define this tag. The OpenAPI Tag objects are used to implement the codelist, whereas the canonical definition is in the codelist. If there are any discrepancies between the description of this OpenAPI Tag and the codelist, the codelist takes priority.",
+        "url": "https://docs.openreferral.org/en/latest/hsds/codelists.html#api-endpoint-requirement"
+      }
+    },
+    {
+      "name": "optional",
+      "description": "This endpoint is OPTIONAL in the HSDS API Specification",
+      "externalDocs": {
+        "description": "This URI points to the codelist file used to define the codes in HSDS which are then used to define this tag. The OpenAPI Tag objects are used to implement the codelist, whereas the canonical definition is in the codelist. If there are any discrepancies between the description of this OpenAPI Tag and the codelist, the codelist takes priority.",
+        "url": "https://docs.openreferral.org/en/latest/hsds/codelists.html#api-endpoint-requirement"
+      }
+    }
+  ],
   "paths": {
     "/": {
       "get": {
         "description": "Retrieve information about this API and its relationship with HSDS.",
         "summary": "Retrieve information about this API and its relationship with HSDS.",
         "operationId": "getAPIMetaInformation",
+        "tags": [
+          "required"
+        ],
         "responses": {
           "200": {
             "description": "A JSON response providing information about this API.",
@@ -36,6 +57,46 @@
                       "type": "string",
                       "format": "uri",
                       "description": "URL of the openapi JSON file which defines this API."
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "A human-readable description of this API feed"
+                    },
+                    "data_guide": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "A URI to a human-readable data guide which can support people understanding this dataset."
+                    },
+                    "publisher": {
+                      "type": "object",
+                      "properties": {
+                        "name": {
+                          "type": "string",
+                          "description": "The name of the publisher of this API feed."
+                        },
+                        "identifier": {
+                          "type": "string",
+                          "description": "An organization identifier string formatted according to org-id.guide e.g. GB-COH-123456."
+                        },
+                        "email": {
+                          "type": "string",
+                          "format": "email",
+                          "description": "An email address that can be used to submit feedback about data in this feed."
+                        },
+                        "website": {
+                          "type": "string",
+                          "format": "uri",
+                          "description": "A URL that can be used to submit feedback about data in this feed."
+                        },
+                        "additional_websites": {
+                          "type": "array",
+                          "description": "Additional URLs that can be used to contact the Publisher about data in this feed.",
+                          "items": {
+                            "type": "string",
+                            "format": "uri"
+                          }
+                        }
+                      }
                     }
                   }
                 }
@@ -61,6 +122,9 @@
         "description": "Retrieve fully nested service with all related data with id.",
         "summary": "Retrieves a fully nested service with all related data with id.",
         "operationId": "getFullyNestedServiceById",
+        "tags": [
+          "required"
+        ],
         "responses": {
           "200": {
             "description": "A Service matching the {id}, with all related data according to the HSDS Specification for Service.",
@@ -80,6 +144,9 @@
         "description": "Retrieve fully nested service with all related data with id.",
         "summary": "Retrieves paginated listings of services that only have one-to-one fields in them.",
         "operationId": "getPaginatedListOfServices",
+        "tags": [
+          "required"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -143,6 +210,9 @@
         "description": "Retrieve fully nested service with all related data with id.",
         "summary": "Retrieves paginated listings of services that only have one-to-one fields in them.",
         "operationId": "getPaginatedListOfServices",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -219,6 +289,9 @@
         "description": "Full information on taxonomy.",
         "summary": "Retrieves full information on a taxonomy by {id}.",
         "operationId": "getTaxonomyById",
+        "tags": [
+          "optional"
+        ],
         "responses": {
           "200": {
             "description": "Full information on taxonomy.",
@@ -238,6 +311,9 @@
         "description": "Paginated listing of taxonomies.",
         "summary": "Paginated listing of taxonomies.",
         "operationId": "getPaginatedListOfTaxonomies",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -281,6 +357,9 @@
         "description": "Paginated listing of taxonomies.",
         "summary": "Paginated listing of taxonomies.",
         "operationId": "getPaginatedListOfTaxonomies",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -337,6 +416,9 @@
         "description": "Full information on a taxonomy term.",
         "summary": "Full information on a taxonomy term.",
         "operationId": "getPaginatedListOfTaxonomyTerms",
+        "tags": [
+          "optional"
+        ],
         "responses": {
           "200": {
             "description": "Full information on a taxonomy term.",
@@ -356,6 +438,9 @@
         "description": "Full information on a taxonomy term",
         "summary": "Paginated listing of taxonomy terms",
         "operationId": "getTaxonomyTermById",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -420,6 +505,9 @@
         "description": "Full information on a taxonomy term",
         "summary": "Paginated listing of taxonomy terms",
         "operationId": "getTaxonomyTermById",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -497,6 +585,9 @@
         "description": "Fully nested organization with service array that contains simple information which could only contain the service.id.",
         "summary": "Fully nested organization with service array that contains simple information which could only contain the service.id.",
         "operationId": "getOrganizationById",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/full_service"
@@ -521,6 +612,9 @@
         "description": "Paginated list of basic Organization information.",
         "summary": "Paginated list of basic Organization information",
         "operationId": "getPaginatedListOfOrganizations",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -577,6 +671,9 @@
         "description": "Paginated list of basic Organization information.",
         "summary": "Paginated list of basic Organization information",
         "operationId": "getPaginatedListOfOrganizations",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -646,6 +743,9 @@
         "description": "Retrieve fully nested service_at_location with all related data with specified id.",
         "summary": "Retrieve fully nested service_at_location with all related data with specified id.",
         "operationId": "getServiceAtLocationWithNestedDataById",
+        "tags": [
+          "optional"
+        ],
         "responses": {
           "200": {
             "description": "Retrieve fully nested service_at_location with all related data with specified id.",
@@ -665,6 +765,9 @@
         "description": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
         "summary": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
         "operationId": "getPaginatedListOfServiceAtLocation",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
@@ -730,6 +833,9 @@
         "description": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
         "summary": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
         "operationId": "getPaginatedListOfServiceAtLocation",
+        "tags": [
+          "optional"
+        ],
         "parameters": [
           {
             "$ref": "#/components/parameters/search"
diff --git a/docs/hsds/api_reference.md b/docs/hsds/api_reference.md
@@ -7,12 +7,16 @@ Unlike with the HSDS Schemas where we can provide canonical JSON Schema represen
 
 To overcome this limitation, the API specification on this page uses the key words "MUST", "REQUIRED" and "OPTIONAL" in accordance with [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) to describe whether each endpoint is required by the API Specification. This is used alongside the details of the canonical OpenAPI formatted reference file to measure compliance with the API Specification.
 
-The current canonical HSDS API specification in OpenAPI 3.1 format is available at the following URL: [https://raw.githubusercontent.com/openreferral/specification/3.0/schema/openapi.json](https://raw.githubusercontent.com/openreferral/specification/3.0/schema/openapi.json)
+The current canonical HSDS API specification in OpenAPI 3.1 format is available at the following URL: [https://raw.githubusercontent.com/openreferral/specification/3.2/schema/openapi.json](https://raw.githubusercontent.com/openreferral/specification/3.2/schema/openapi.json)
 
 For those more familiar with tools such as SwaggerUI, we provide [a Swagger UI representation](../extras/openapi.html). Readers should note that due to incompatibilities between Swagger UI and OpenAPI 3.1, the file powering the Swagger UI representation is compiled from the canonical HSDS API specification file. Therefore if there are any conflicts between the Swagger UI representation and the specification defined on this API Reference page, then *this specification takes precedence*.
 
 If there are errors or omissions in this API specification, you are encouraged to raise issues on [on the issue tracker](https://github.com/openreferral/specification/issues).
 
+## OpenAPI Tags
+
+The OpenAPI specification makes use of OpenAPI's [Tag object](https://spec.openapis.org/oas/latest.html#tag-object) to tad endpoints with tags drawn from the [API Endpoint Requirement codelist](./codelists.md#api-endpoint-requirement). For convenience, these codes and definitions have been reproduced in the OpenAPI file as `Tag`s. If there are any discrepencies between the definitions of these terms between the canonical codelists and the corresponding `Tag` objects in the OpenAPI file; **the canonical codelists take precedence**.
+
 ## Lists and Pagination
 
 API endpoints that return lists of entities, such as services returned by a `/services` endpoint MUST be paginated. To support this, the HSDS API reference defines the `Page` schema:
diff --git a/docs/hsds/changelog.md b/docs/hsds/changelog.md
@@ -3,6 +3,36 @@ Changelog
 
 This page provides the list of changes that have been made to the HSDS schema.
 
+## [v3.2](https://github.com/openreferral/specification/releases/tag/v3.2)
+
+### New codelists
+
+* Added the [API Endpoint Requirement codelist](https://docs.openreferral.org/en/latest/codelists.html#api-endpoint-requirement)
+
+### Backwards compatible API changes
+
+* New optional `publisher` property on the response schema to `GET /`
+* New optional `data_guide` property on the response schema to `GET /`
+* New `Tag` objects defined in the canonical openapi.json file, which match codes defined in the new API Endpoint Requirement codelist: `required` and `optional`
+  * Applied `required` tag to the following endpoints:
+    * `GET /` 
+    * `GET /services/{id}`
+    * `GET /services`
+  * Applied `optional` tag to the following endpoints:
+    * `GET /taxonomies/{id}`
+    * `GET /taxonomies`
+    * `GET /taxonomy_terms/{id}`
+    * `GET /taxonomy_terms`
+    * `GET /organizations/{id}`
+    * `GET /organizations`
+    * `GET /service_at_locations/{id}`
+    * `GET /service_at_locations`
+    * `POST /services`
+    * `POST /taxonomies`
+    * `POST /taxonomy_terms`
+    * `POST /organizations`
+    * `POST /service_at_locations`
+
 ## [v3.1.1](https://github.com/openreferral/specification/releases/tag/v3.1.1)
 
 * Made `Page.Empty` a required field for API responses
diff --git a/docs/hsds/codelists.md b/docs/hsds/codelists.md
@@ -0,0 +1,18 @@
+Codelists Reference
+=====================
+
+Some schema and API References fields refer to codelists which help interoperability by standardizing and limiting the possible values of fields.
+
+At this moment in time, the Human Services Data Specification only uses a single codelist: the API Required codelist.
+
+## API Endpoint Requirement
+This is used to define codes which are then implemented by the OpenAPI file &mdash; representing the [API Reference](api_reference.md) &mdash; as `Tag` objects and then used to tag particular operations defined in the file as required by the specification or not.
+
+This codelist is the result of a knowledge exchange with [CommonGrants](https://commongrants.org/), who implement a similar system to overcome the challenge of using OpenAPI to encode an API Reference.
+
+```{eval-rst}
+.. csv-table:: 
+   :file: ../../schema/codelists/api-endpoint-requirement.csv
+   :header-rows: 1
+   :widths: auto
+```
diff --git a/docs/hsds/database_schemas.md b/docs/hsds/database_schemas.md
@@ -9,6 +9,6 @@ HSDS is an exchange format designed to standardise the format for outputting mac
 
 This being established, we provide some pre-rolled database schemas in order to support people and organizations bootstrapping systems which will work with HSDS data. We provide these in the form of `.sql` query files which &mdash; when executed in an appropriate environment &mdash; will generate database schemas with tables useful for storing and retrieving HSDS data. We geneate these files directly from the HSDS schema files, so they update as we release new versions of the specification.
 
-You can find the latest version of these files in the `/database` directory of the HSDS Specification Github repository. We provide versions for each SQL and PostgreSQL format databases. The files for HSDS version 3.1 are linked below:
+You can find the latest version of these files in the `/database` directory of the HSDS Specification Github repository. We provide versions for each SQL and PostgreSQL format databases. The files for HSDS version 3.2 are linked below:
 
-* [Database schemas for HSDS 3.1](https://github.com/openreferral/specification/tree/3.1/database)
+* [Database schemas for HSDS 3.1](https://github.com/openreferral/specification/tree/3.2/database)
diff --git a/docs/index.md b/docs/index.md
@@ -58,6 +58,7 @@ Contents:
 
    hsds/overview
    hsds/schema_reference
+   hsds/codelists
    hsds/api_reference
    hsds/serialization
    hsds/identifiers
diff --git a/schema/codelists/api-endpoint-requirement.csv b/schema/codelists/api-endpoint-requirement.csv
@@ -0,0 +1,3 @@
+Code,Title,Description
+"required","Required","This endpoint is REQUIRED by the HSDS API Specification"
+"optional","Optional","This endpoint is OPTIONAL in the HSDS API Specification"
diff --git a/schema/openapi.json b/schema/openapi.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Code,Title,Description`
	`2`	`+"required","Required","This endpoint is REQUIRED by the HSDS API Specification"`
	`3`	`+"optional","Optional","This endpoint is OPTIONAL in the HSDS API Specification"`