diff --git a/schemas/changelog.md b/schemas/changelog.md index c6b3892..42c6d41 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -25,6 +25,7 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche - [Version 1.1.5 - June 15, 2026 - FHIR Example File Compliance Fixes\*\*](#version-115---june-15-2026---fhir-example-file-compliance-fixes) - [Version 1.1.6 - June 22, 2026 - Add order cancellation\*\*](#version-116---june-22-2026---add-order-cancellation) - [Version 1.1.7 - July 7, 2026 - Aligned API spec for APIM publication](#version-117---july-7-2026---aligned-api-spec-for-apim-publication) + - [Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas for category and businessStatus](#version-118---july-22-2026---typed-codeableconcept-schemas) --- @@ -389,3 +390,45 @@ Changes to home-test-supplier-api.yaml: 2. Replace the `BearerAuth` + `NHS_Login` security schemes with a single `bearerAuth` (system-to-system consumers; no NHS Login) 3. Add `servers` (APIM sandbox URL) and `x-spec-publication` (Try this API disabled) + +--- + +## Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas + +Changes to home-test-supplier-api.yaml: + +1. Added typed CodeableConcept schemas to constrain category and +businessStatus values + + - Created `FHIRDiagnosticCoding` schema (replaces generic + FHIRCodeableConcept for DiagnosticReport.category) + - Requires `text` field typed to `FHIRDiagnosticCodingText` + - Includes example with LAB coding from + `http://terminology.hl7.org/CodeSystem/v2-0074` + - Created `FHIRDiagnosticCodingText` enum schema with allowed value: + `Laboratory` + - Created `FHIRObservationCoding` schema (replaces generic + FHIRCodeableConcept Observation.category) + - Requires `text` field typed to `FHIRObservationCodingText` + - Includes example with laboratory coding from + `http://terminology.hl7.org/CodeSystem/observation-category` + - Created `FHIRObservationCodingText` enum schema with allowed value: + `Laboratory` + - Created `FHIRBusinessStatusCoding` schema for Task.businessStatus + - Requires `text` field typed to `FHIRBusinessStatusCodingText` + - Created `FHIRBusinessStatusCodingText` enum schema with allowed values. + +2. Updated DiagnosticReport.category to reference new typed schema + - Changed `items` + from `$ref: "#/components/schemas/FHIRCodeableConcept"` + to `$ref: "#/components/schemas/FHIRDiagnosticCoding"` + +3. Updated Observation.category to reference new typed schema + - Changed `items` + from `$ref: "#/components/schemas/FHIRCodeableConcept"` + to `$ref: "#/components/schemas/FHIRObservationCoding"` + +4. Formatting: expanded inline enum arrays to multi-line format for + readability + - Affected enums: Communication.status, FHIRTask.status, + OperationOutcome.issue.severity, FHIRIdentifier.use diff --git a/schemas/home-test-supplier-api.yaml b/schemas/home-test-supplier-api.yaml index 5e244b8..97613e0 100644 --- a/schemas/home-test-supplier-api.yaml +++ b/schemas/home-test-supplier-api.yaml @@ -86,7 +86,7 @@ info: ## Onboarding Contact the HomeTest team to agree onboarding, supplier responsibilities and access to test environments. - version: 1.1.7 + version: 1.1.8 contact: name: NHS England - Digital Prevention Services Portfolio - Home Test Team email: england.hometest@nhs.net @@ -333,7 +333,7 @@ components: type: array minItems: 1 items: - $ref: "#/components/schemas/FHIRCodeableConcept" + $ref: "#/components/schemas/FHIRDiagnosticCoding" description: Category of the diagnostic report (should be LAB/Laboratory for test results) example: - coding: @@ -411,7 +411,7 @@ components: type: array minItems: 1 items: - $ref: "#/components/schemas/FHIRCodeableConcept" + $ref: "#/components/schemas/FHIRObservationCoding" description: Category of the observation (should be laboratory/Laboratory for observation category) example: - coding: @@ -480,7 +480,12 @@ components: status: type: string description: Status of the communication event. For results, 'completed' should be used for when clinical contact has been made. When clinical contact has not been made, 'on-hold' should be used until contact is made. If contact is not required, such as for non-reactive results, then 'not-done' should be used. - enum: [completed, on-hold, not-done] + enum: + [ + completed, + on-hold, + not-done, + ] example: "not-done" reasonReference: type: array @@ -526,11 +531,15 @@ components: status: type: string description: Current status of the task - FHIR standard values (use businessStatus for domain-specific states) - enum: [accepted, in-progress] + enum: + [ + accepted, + in-progress, + ] example: "in-progress" businessStatus: allOf: - - $ref: "#/components/schemas/FHIRCodeableConcept" + - $ref: "#/components/schemas/FHIRBusinessStatusCoding" - description: Domain-specific business status, expected to be one of "dispatched","received-at-lab", or "test-processed" for HomeTest. example: text: "dispatched" @@ -601,7 +610,13 @@ components: severity: type: string description: Severity of the issue - enum: [fatal, error, warning, information] + enum: + [ + fatal, + error, + warning, + information, + ] example: "error" code: type: string @@ -739,8 +754,88 @@ components: use: type: string description: The purpose of this identifier - enum: [usual, official, temp, secondary, old] + enum: + [ + usual, + official, + temp, + secondary, + old, + ] example: "official" + FHIRBusinessStatusCoding: + type: object + description: A specific example of a CodeableConcept for status updates, using the businessStatus field of the FHIRTask + required: + - text + properties: + coding: + type: array + description: Code defined by a terminology system + items: + $ref: '#/components/schemas/FHIRCoding' + text: + $ref: '#/components/schemas/FHIRBusinessStatusCodingText' + description: Business status category text. + example: dispatched + FHIRBusinessStatusCodingText: + type: string + description: Business status values. + enum: + [ + order-accepted, + dispatched, + received-at-lab, + test-processed, + ] + FHIRDiagnosticCoding: + type: object + description: A specific example of a CodeableConcept for DiagnosticReport category. + required: + - text + properties: + coding: + type: array + description: Code defined by a terminology system + items: + $ref: '#/components/schemas/FHIRCoding' + text: + $ref: '#/components/schemas/FHIRDiagnosticCodingText' + description: Diagnostic report status text. + example: + coding: + - system: "http://terminology.hl7.org/CodeSystem/v2-0074" + code: "LAB" + display: "Laboratory" + text: Laboratory + FHIRDiagnosticCodingText: + type: string + description: Diagnostic report category status values. + enum: [Laboratory] + FHIRObservationCoding: + type: object + description: A specific example of a CodeableConcept for Observation category. + required: + - text + properties: + coding: + type: array + description: Code defined by a terminology system + items: + $ref: '#/components/schemas/FHIRCoding' + text: + $ref: '#/components/schemas/FHIRObservationCodingText' + description: Observation category status values + example: + coding: + - system: "http://terminology.hl7.org/CodeSystem/observation-category" + code: "laboratory" + display: "Laboratory" + text: Laboratory + FHIRObservationCodingText: + type: string + description: Observation category status values. + enum: [Laboratory] examples: FHIRBundleResultsExample: summary: Example FHIR Bundle for test results submission