From fb9a4b95000fde59b4f7b9e04d8d735c99f594de Mon Sep 17 00:00:00 2001 From: iichr Date: Tue, 4 Aug 2026 17:27:29 +0100 Subject: [PATCH 1/3] feat: update spec to add app-level3 auth and new integration env --- schemas/changelog.md | 16 +++++++++++ schemas/home-test-supplier-api.yaml | 43 +++++++++++++++++++++-------- 2 files changed, 48 insertions(+), 11 deletions(-) diff --git a/schemas/changelog.md b/schemas/changelog.md index bede947..d22adcf 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -31,6 +31,22 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche --- +## Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access + +Changes to `home-test-supplier-api.yaml`: + +1. Replaced the generic bearer authentication scheme with APIM's `app-level3` + application-restricted signed-JWT security scheme. +2. Documented that suppliers authenticate their application, not an end user, + and linked to the NHS signed-JWT integration guide. +3. Added the sandbox, integration and production environment table. Only the + sandbox URL is currently available; integration and production remain + unavailable. +4. Corrected the sandbox documentation to state that it returns canned + responses and enabled "Try this API". + +--- + ## Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support Changes to supplier-api-spec-v2.yaml (new file, v1 remains unchanged): diff --git a/schemas/home-test-supplier-api.yaml b/schemas/home-test-supplier-api.yaml index e490331..511d88d 100644 --- a/schemas/home-test-supplier-api.yaml +++ b/schemas/home-test-supplier-api.yaml @@ -59,9 +59,14 @@ info: ## Security and authorisation - This draft uses bearer token authorisation because suppliers are system-to-system API consumers. + This API is application-restricted: we authenticate the calling supplier + application, but not an end user. - The final access level must be confirmed with the NHS API Platform team before production use. + Suppliers use this API unattended, with no end user present, to submit test + results and test-order status updates to HomeTest. + + To use this access mode, follow + [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication). ## Errors @@ -79,21 +84,39 @@ info: ## Environments and testing - A sandbox has been deployed to the NHS API Platform and is available under the `https://sandbox.api.service.nhs.uk/hometest-api` base URL. + | Environment | Base URL | + | --- | --- | + | Sandbox | `https://sandbox.api.service.nhs.uk/hometest-api` | + | Integration | Not yet available | + | Production | Not yet available | + + ### Sandbox environment + + Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): + + * is for early developer testing + * is open access, so does not allow suppliers to test authorisation + * returns canned example responses rather than processing live data. + + "Try this API" is enabled for this sandbox specification. + + ### Integration and production environments - The "Try this API" feature is disabled for this documentation-only publication until a sandbox endpoint is available. + Integration and production environments are not yet available. Integration + will support formal supplier testing with authorisation; production will + process live service requests. ## Onboarding Contact the HomeTest team to agree onboarding, supplier responsibilities and access to test environments. - version: 1.1.8 + version: 1.1.9 contact: name: NHS England - Digital Prevention Services Portfolio - Home Test Team email: england.hometest@nhs.net x-spec-publication: try-this-api: - disabled: true + disabled: false servers: - url: https://sandbox.api.service.nhs.uk/hometest-api @@ -1215,13 +1238,11 @@ components: diagnostics: "The requested order could not be found" securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT + app-level3: + $ref: https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3 security: - - bearerAuth: [] + - app-level3: [] tags: - name: Order Management From df9ec64ec15d88b3ba4c494bc21d23b2a442b85b Mon Sep 17 00:00:00 2001 From: iichr Date: Fri, 7 Aug 2026 11:02:09 +0100 Subject: [PATCH 2/3] feat: bump spec up to 2.0.2 --- schemas/changelog.md | 3 ++- schemas/home-test-supplier-api.yaml | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/schemas/changelog.md b/schemas/changelog.md index d22adcf..0888c4b 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -8,6 +8,7 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche - [Changelog](#changelog) - [Table of Contents](#table-of-contents) + - [Version 2.0.2 - August 13, 2026 - Document APIM application-restricted access](#version-202---august-13-2026---document-apim-application-restricted-access) - [Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support](#version-200---july-20-2026---acute-consumer-order-support) - [Version 1.0.1](#version-101) - [Version 1.0.2 - January 26, 2026 - Additional FHIR Compliance Updates](#version-102---january-26-2026---additional-fhir-compliance-updates) @@ -31,7 +32,7 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche --- -## Version 1.1.9 - August 4, 2026 - Document APIM application-restricted access +## Version 2.0.2 - August 13, 2026 - Document APIM application-restricted access Changes to `home-test-supplier-api.yaml`: diff --git a/schemas/home-test-supplier-api.yaml b/schemas/home-test-supplier-api.yaml index 511d88d..d9f5081 100644 --- a/schemas/home-test-supplier-api.yaml +++ b/schemas/home-test-supplier-api.yaml @@ -109,7 +109,7 @@ info: ## Onboarding Contact the HomeTest team to agree onboarding, supplier responsibilities and access to test environments. - version: 1.1.9 + version: 2.0.2 contact: name: NHS England - Digital Prevention Services Portfolio - Home Test Team email: england.hometest@nhs.net From 1f1be91635f1af2ca208be4eeac6a09b3fb802c5 Mon Sep 17 00:00:00 2001 From: iichr Date: Thu, 13 Aug 2026 12:30:00 +0100 Subject: [PATCH 3/3] feat: changelog ordered by semantic version (latest first) with all content preserved --- schemas/changelog.md | 622 +++++++++++++++++++++---------------------- 1 file changed, 311 insertions(+), 311 deletions(-) diff --git a/schemas/changelog.md b/schemas/changelog.md index 0888c4b..709943c 100644 --- a/schemas/changelog.md +++ b/schemas/changelog.md @@ -9,26 +9,26 @@ All notable changes to the NHS Home Test Supplier Integration Framework API sche - [Changelog](#changelog) - [Table of Contents](#table-of-contents) - [Version 2.0.2 - August 13, 2026 - Document APIM application-restricted access](#version-202---august-13-2026---document-apim-application-restricted-access) + - [Version 2.0.1 - August 10, 2026 - Make patient email optional](#version-201----august-10-2026---make-patient-email-optional) - [Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support](#version-200---july-20-2026---acute-consumer-order-support) - - [Version 1.0.1](#version-101) - - [Version 1.0.2 - January 26, 2026 - Additional FHIR Compliance Updates](#version-102---january-26-2026---additional-fhir-compliance-updates) - - [Version 1.0.3 - January 27, 2026 - FHIR R4 Validation and UUID Corrections](#version-103---january-27-2026---fhir-r4-validation-and-uuid-corrections) - - [Version 1.0.4 - January 27, 2026 - Business-Critical Required Fields (FHIR Profiling)](#version-104---january-27-2026---business-critical-required-fields-fhir-profiling) - - [Version 1.0.5 - March 10, 2026 - Example and Required Field Corrections](#version-105---march-10-2026---example-and-required-field-corrections) - - [Version 1.0.6 - March 20, 2026 - Status Endpoint Method Update](#version-106---march-20-2026---status-endpoint-method-update) - - [Version 1.0.7 - April 8, 2026 - Performer Example Update](#version-107---april-8-2026---performer-example-update) - - [Version 1.0.8 - April 16, 2026 -](#version-108---april-16-2026--) - - [Version 1.0.9 - April 24, 2026 -](#version-109---april-24-2026--) - - [Version 1.1.0 - May 8, 2026 - Add Supplier Eligibility Check Endpoint](#version-110---may-8-2026---add-supplier-eligibility-check-endpoint) - - [Version 1.1.1 - May 12, 2026 - Add discriminator to OpenAPI specs](#version-111---may-12-2026---add-discriminator-to-openapi-specs) - - [Version 1.1.2 - May 18, 2026 - Additional DataAbsent Result reason](#version-112---may-18-2026---additional-dataabsent-result-reason) - - [Version 1.1.3 - June 1, 2026 - Change handling of non-definitive results](#version-113---june-1-2026---change-handling-of-non-definitive-results) - - [Version 1.1.4 - June 10, 2026 - Resolve OpenAPI spec Spectral validation warnings](#version-114---june-10-2026---resolve-openapi-spec-spectral-validation-warnings) - - [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](#version-118---july-22-2026---typed-codeableconcept-schemas) - - [Version 2.0.1 - August 10, 2026 - Make patient email optional](#version-201----august-10-2026---make-patient-email-optional) + - [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.6 - June 22, 2026 - Add order cancellation\*\*](#version-116---june-22-2026---add-order-cancellation) + - [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.4 - June 10, 2026 - Resolve OpenAPI spec Spectral validation warnings](#version-114---june-10-2026---resolve-openapi-spec-spectral-validation-warnings) + - [Version 1.1.3 - June 1, 2026 - Change handling of non-definitive results](#version-113---june-1-2026---change-handling-of-non-definitive-results) + - [Version 1.1.2 - May 18, 2026 - Additional DataAbsent Result reason](#version-112---may-18-2026---additional-dataabsent-result-reason) + - [Version 1.1.1 - May 12, 2026 - Add discriminator to OpenAPI specs](#version-111---may-12-2026---add-discriminator-to-openapi-specs) + - [Version 1.1.0 - May 8, 2026 - Add Supplier Eligibility Check Endpoint](#version-110---may-8-2026---add-supplier-eligibility-check-endpoint) + - [Version 1.0.9 - April 24, 2026 -](#version-109---april-24-2026--) + - [Version 1.0.8 - April 16, 2026 -](#version-108---april-16-2026--) + - [Version 1.0.7 - April 8, 2026 - Performer Example Update](#version-107---april-8-2026---performer-example-update) + - [Version 1.0.6 - March 20, 2026 - Status Endpoint Method Update](#version-106---march-20-2026---status-endpoint-method-update) + - [Version 1.0.5 - March 10, 2026 - Example and Required Field Corrections](#version-105---march-10-2026---example-and-required-field-corrections) + - [Version 1.0.4 - January 27, 2026 - Business-Critical Required Fields (FHIR Profiling)](#version-104---january-27-2026---business-critical-required-fields-fhir-profiling) + - [Version 1.0.3 - January 27, 2026 - FHIR R4 Validation and UUID Corrections](#version-103---january-27-2026---fhir-r4-validation-and-uuid-corrections) + - [Version 1.0.2 - January 26, 2026 - Additional FHIR Compliance Updates](#version-102---january-26-2026---additional-fhir-compliance-updates) + - [Version 1.0.1](#version-101) --- @@ -48,6 +48,12 @@ Changes to `home-test-supplier-api.yaml`: --- +## Version 2.0.1 - August 10, 2026 - Make patient email optional + +Changes to supplier-api-spec.yaml: + +1. Make email optional in the contained Patient resource. This was a mistake confirmed during testing, as the HomeTest user journey has the patient email as an optional field. The patient's phone number is still mandatory. + ## Version 2.0.0 - July 20, 2026 - Acute Consumer Order Support Changes to supplier-api-spec-v2.yaml (new file, v1 remains unchanged): @@ -80,240 +86,159 @@ Changes to supplier-api-spec-v2.yaml (new file, v1 remains unchanged): --- -## Version 1.0.1 +## Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas ---- +Changes to home-test-supplier-api.yaml: -Changes to supplier_api_spec.yaml +1. Added typed CodeableConcept schemas to constrain category and +businessStatus values -1. Fixed FHIR ServiceRequest Structure - - Added missing status property with FHIR-standard enum values - - Added text field to code (CodeableConcept) for human-readable representation - - Moved patient demographics from custom fields to a FHIR-compliant contained Patient resource - Changed from custom fields (firstName, lastName, phone, address.line1/line2/postcode, etc.) - To FHIR datatypes: name (HumanName), telecom (ContactPoint), address (Address with postalCode), birthDate - - Made subject a minimal Reference pointing to #patient-1 (contained resource) -2. Updated FHIRObservation - - Added text field to code (CodeableConcept) - - Removed valueQuantity (numeric results) - - Added interpretation field with FHIR ObservationInterpretation CodeableConcept - - Kept valueCodeableConcept for actual test results -3. Made /results Strictly FHIR - - Changed 200 response from custom {results: []} to FHIR Bundle (type: searchset) - - Added FHIRBundleSearchsetObservations schema - - Changed 400 error from application/problem+json to application/fhir+json with OperationOutcome - - Changed 404 error to return OperationOutcome -4. Updated All Error Responses to FHIR - - Replaced BadRequest (400) from RFC 7807 to FHIR OperationOutcome - - Replaced UnprocessableEntity (422) from RFC 7807 to FHIR OperationOutcome - - All errors now use application/fhir+json consistently -5. Made Success Responses FHIR-Compliant - - Changed POST /order 201 response from custom JSON {order_uid, order_status, estimated_delivery_date} to return the FHIR ServiceRequest resource + - 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"` -Changes to home-test-supplier-api.yaml +3. Updated Observation.category to reference new typed schema + - Changed `items` + from `$ref: "#/components/schemas/FHIRCodeableConcept"` + to `$ref: "#/components/schemas/FHIRObservationCoding"` -1. Fixed FHIRTask Status - - Changed status enum from custom values [`order-received`, `dispatched`, `received-at-lab`, `complete`] - - To FHIR-standard values: [`draft`, `requested`, `received`, `accepted`, `rejected`, `ready`, `cancelled`, `in-progress`, `on-hold`, `failed`, `completed`, `entered-in-error`] - > [!NOTE] - > We will map these FHIR status from our agreed status and update later - - Updated businessStatus description to indicate it holds domain-specific statuses -2. Updated FHIRObservation - - Added text field to code (CodeableConcept) - - Removed valueQuantity (numeric results) - - Added interpretation field with FHIR ObservationInterpretation CodeableConcept - - Kept valueCodeableConcept for actual test results -3. Added FHIROperationOutcome Schema - - Full FHIR-compliant OperationOutcome resource definition -4. Updated All Error Responses to FHIR - - Replaced BadRequest (400) from RFC 7807 to FHIR OperationOutcome - - Replaced Unauthorized (401) from RFC 7807 to FHIR OperationOutcome - - Replaced NotFound (404) from RFC 7807 to FHIR OperationOutcome - - All errors now use application/fhir+json consistently -5. Made Success Responses FHIR-Compliant - - Changed POST /result 201 response from custom JSON {order_uid, result_status, timestamp} to return the FHIR Observation resource +4. Formatting: expanded inline enum arrays to multi-line format for + readability + - Affected enums: Communication.status, FHIRTask.status, + OperationOutcome.issue.severity, FHIRIdentifier.use --- -## Version 1.0.2 - January 26, 2026 - Additional FHIR Compliance Updates +## Version 1.1.7 - July 7, 2026 - Aligned API spec for APIM publication -Changes to both supplier_api_spec.yaml and home-test-supplier-api.yaml: +Changes to home-test-supplier-api.yaml: -1. Added FHIRReference Reusable Schema - - Created FHIRReference component schema for proper FHIR Reference datatype - - Schema includes: - - reference (required): Literal reference, Relative, internal or absolute URL - - type (optional): Type the reference refers to (e.g., "Organization") - - display (optional): Text alternative for the resource - - Ensures proper typing for code generation (TypeScript/Java/C#) +1. Add the full APIM documentation in `info.description` in accordance with the published style guides (new sections added - overview, who can use, related APIs, status, service level, technology, network access, security, errors, open source, environments, onboarding) -2. Updated All Reference Fields in supplier_api_spec.yaml - - ServiceRequest.subject: Changed from inline object to use FHIRReference with allOf - - ServiceRequest.requester: Changed from inline object to use FHIRReference with allOf - - ServiceRequest.performer: Changed from inline object array to FHIRReference array - - Observation.basedOn: Changed from inline object array to FHIRReference array - - Observation.subject: Changed from inline object to use FHIRReference with allOf - - Observation.performer: Changed from inline object array to FHIRReference array +2. Replace the `BearerAuth` + `NHS_Login` security schemes with a single `bearerAuth` (system-to-system consumers; no NHS Login) -3. Updated All Reference Fields in home-test-supplier-api.yaml - - Observation.basedOn: Changed from inline object array to FHIRReference array - - Observation.subject: Changed from inline object to use FHIRReference with allOf - - Observation.performer: Changed from inline object array to FHIRReference array - - Task.basedOn: Changed from inline object array to FHIRReference array - - Task.for: Changed from inline object to use FHIRReference with allOf - - Task.requester: Changed from inline object to use FHIRReference with allOf - - Task.owner: Changed from inline object to use FHIRReference with allOf +3. Add `servers` (APIM sandbox URL) and `x-spec-publication` (Try this API disabled) -4. Fixed FHIRTask FHIR R4 Compliance - - Added required intent field with enum values: [`unknown`, `proposal`, `plan`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option`] - - Updated required fields to include: resourceType, status, intent, basedOn +--- -5. Added FHIRCodeableConcept Reusable Schema - - Created FHIRCodeableConcept component schema for proper FHIR CodeableConcept datatype - - Schema includes: - - coding (optional): Array of Coding objects with system, code, and display - - text (optional): Plain text representation of the concept - - Ensures proper typing for code generation and consistency across all coded values +## Version 1.1.6 - June 22, 2026 - Add order cancellation\*\* -6. Updated All CodeableConcept Fields in supplier-api-spec.yaml - - ServiceRequest.code: Changed from inline object to use FHIRCodeableConcept with allOf - - Observation.code: Changed from inline object to use FHIRCodeableConcept with allOf - - Observation.interpretation: Changed from inline object array to FHIRCodeableConcept array - - Observation.valueCodeableConcept: Changed from inline object to use FHIRCodeableConcept with allOf +1. Add order cancellation process + - Allow 'revoked' as a status of the ServiceRequest + - Use 'DELETE' verb on the /order endpoint when orders are being cancelled. This allows specific errors to be defined, and helps to separate cancellation from creating a new order. + - Add documentation for rejection of further updates to cancelled orders -7. Updated All CodeableConcept Fields in home-test-supplier-api.yaml - - Observation.code: Changed from inline object to use FHIRCodeableConcept with allOf - - Observation.interpretation: Changed from inline object array to FHIRCodeableConcept array - - Observation.valueCodeableConcept: Changed from inline object to use FHIRCodeableConcept with allOf - - Task.statusReason: Changed from inline object to use FHIRCodeableConcept with allOf - - Task.businessStatus: Changed from inline object to use FHIRCodeableConcept with allOf +2. Clarify the order eligibility check and other order states + - Remove mentions of order rejection + - Add diagram for order states + - Add documentation for order cancellation, and order acceptance (via eligibility check) -8. Added Reusable FHIR Datatype Schemas - - Created FHIRCoding component schema for proper FHIR Coding datatype - - Properties: system, code, display - - Used within FHIRCodeableConcept.coding arrays - - Created FHIRIdentifier component schema for proper FHIR Identifier datatype - - Properties: system, value, use - - Used in Task.identifier arrays - - Created FHIRHumanName component schema for proper FHIR HumanName datatype - - Properties: use, family, given, text - - Used in Patient.name arrays (supplier-api-spec only) - - Created FHIRContactPoint component schema for proper FHIR ContactPoint datatype - - Properties: system, value, use - - Used in Patient.telecom arrays (supplier-api-spec only) - - Created FHIRAddress component schema for proper FHIR Address datatype - - Properties: use, type, line, city, postalCode, country - - Used in Patient.address arrays (supplier-api-spec only) +--- -9. Updated All Inline Datatype Usages in supplier-api-spec.yaml - - FHIRCodeableConcept.coding: Changed from inline Coding objects to FHIRCoding array - - Patient.name (contained): Changed from inline HumanName objects to FHIRHumanName array - - Patient.telecom (contained): Changed from inline ContactPoint objects to FHIRContactPoint array - - Patient.address (contained): Changed from inline Address objects to FHIRAddress array - - OperationOutcome.issue.details: Changed from inline CodeableConcept to FHIRCodeableConcept +## Version 1.1.5 - June 15, 2026 - FHIR Example File Compliance Fixes\*\* -10. Updated All Inline Datatype Usages in home-test-supplier-api.yaml - - FHIRCodeableConcept.coding: Changed from inline Coding objects to FHIRCoding array - - Task.identifier: Changed from inline Identifier objects to FHIRIdentifier array - - OperationOutcome.issue.details: Changed from inline CodeableConcept to FHIRCodeableConcept +Changes to examples/fhir/: -Renamed supplier-api-spec.yaml for conformity +1. Added `text` narrative to all DomainResource examples (dom-6 best practice) + - Added `text.status` and `text.div` to DiagnosticReport, Observation, Communication, ServiceRequest, OperationOutcome, and Task resources across all example files + - Affected files: `observation_non_reactive`, `observation_reactive_with_contact`, `observation_reactive_without_contact`, `observation_insufficient_result`, `observation_invalid_result`, `order_servicerequest`, `ordereligibility_servicerequest`, `ordereligibility_ineligible_operationoutcome`, `operationoutcome_business_rule`, `task_update_dispatched` ---- +2. Added missing `performer` and `effectiveDateTime` to Observation resources (best practice) + - All Observation resources in result bundle examples now include `performer` referencing `Organization/SUP001` + - All Observation resources now include `effectiveDateTime` + - Affected files: `observation_non_reactive`, `observation_reactive_with_contact`, `observation_reactive_without_contact`, `observation_insufficient_result`, `observation_invalid_result` -## Version 1.0.3 - January 27, 2026 - FHIR R4 Validation and UUID Corrections +3. Fixed `dataAbsentReason` to include a coded value from the DataAbsentReason value set + - `observation_insufficient_result`: Added `coding` with `system: http://terminology.hl7.org/CodeSystem/data-absent-reason`, `code: not-performed` + - `observation_invalid_result`: Added `coding` with `code: error` + - Previously only `text` was present, causing a validator warning -Changes to both supplier-api-spec.yaml and home-test-supplier-api.yaml: +4. Fixed `get_test_results_non_reactive` searchset bundle compliance + - Changed `link.self` URL from `/results?order_uid=...` to `Bundle?identifier=...` (resource-type-qualified URL required for type checking) + - Added `search.mode: match` to the outer Bundle entry (required for searchset bundles) -1. Fixed UUID Validation Issues in Observation Resources - - **supplier-api-spec.yaml**: Changed FHIRObservation.id example from "550e8400-e29b-41d4-a716-446655440000" to "550e8400-e29b-41d4-a716-446655440001" - - Reason: Observation ID conflicted with ServiceRequest ID causing reference validation errors - - Ensures unique UUIDs across all resources to prevent FHIR reference mismatches - - **home-test-supplier-api.yaml**: Observation.id example already correctly set to "550e8400-e29b-41d4-a716-446655440001" - - **supplier-api-spec.yaml**: Updated FHIRBundleSearchsetObservations.entry.fullUrl example to "urn:uuid:550e8400-e29b-41d4-a716-446655440001" - - Ensures Bundle fullUrl matches the Observation resource ID - - Critical for FHIR Bundle validation where fullUrl must reference the correct resource +Changes to schemas/fhir-schemas/: ---- +1. Added `text` narrative to all DomainResource schema files (dom-6 best practice) + - Added `text.status` and `text.div` to `Observation.json`, `Task.json`, `OperationOutcome.json`, `ServiceRequest.json`, and `Patient.json` + - Aligns schema files with the same fixes applied to `examples/fhir/` in version 1.1.3 -## Version 1.0.4 - January 27, 2026 - Business-Critical Required Fields (FHIR Profiling) +2. Fixed `Bundle.json` searchset compliance + - Changed `link.self` URL from `/results?order_uid=...` to `Bundle?identifier=...` (resource-type-qualified URL required for FHIR type checking) + - Added `search.mode: match` to the entry (required for searchset bundles) + - Added `text` narrative to the inner Observation resource -Changes to both supplier-api-spec.yaml and home-test-supplier-api.yaml: -Added Required Fields for Business Operations (FHIR Constrained Profile) +--- -1. FHIRServiceRequest Required Fields Added (supplier-api-spec.yaml only) - - Made `contained` required (minItems: 1) - Patient demographics are mandatory for order fulfillment - - Made contained Patient properties required: - - `resourceType` - Required for FHIR resource type identification - - `id` - Required for contained resource reference (#patient-1) - - `name` - Required (patient identification for order processing) - - `telecom` - Required (contact information for delivery and follow-up) - - `address` - Required (shipping address for test kit delivery) - -2. FHIRObservation Required Fields Added (both APIs) - - Made `basedOn` required - Links Observation to originating ServiceRequest (critical for order tracking) - - Made `valueCodeableConcept` required - The actual test result must be present (core purpose of Observation) - -3. FHIRTask Required Fields Added (home-test-supplier-api.yaml only) - - Made `identifier` required - Essential for tracking order status across systems - -4. FHIR Datatype Required Fields Added (supplier-api-spec.yaml only) - - FHIRHumanName: Made `family` required - Last name is mandatory for patient identification - - FHIRContactPoint: Made `value` required - Contact method is useless without actual contact value - - FHIRAddress: Made `line` and `postalCode` required - Minimum address information for UK deliveries +## Version 1.1.4 - June 10, 2026 - Resolve OpenAPI spec Spectral validation warnings -5. Patient Telecom Cardinality Constraint Added (supplier-api-spec.yaml only) - - Made Patient.telecom `minItems: 2` - Requires at least 2 contact points - - Updated description to clarify both phone and email are required - - **Business Rationale**: Both phone (for delivery contact) and email are essential for order fulfillment and customer communication - - **Implementation Note**: Application validation should verify one telecom has `system: 'phone'` and one has `system: 'email'` +1. Resolved errors produced from Spectral OpenAPI spec validation. + - Adding contact field + - Adding operationIDs for all endpoints + - Adding tags + - Updating 'uri' to 'uri-reference' in the format field of the urls + - +2. Some updates to the Spectral validation, but currently still needs to be run manually --- -## Version 1.0.5 - March 10, 2026 - Example and Required Field Corrections - -Changes to home-test-supplier-api.yaml: - -1. Fixed basedOn Example Values +## Version 1.1.3 - June 1, 2026 - Change handling of non-definitive results -- FHIRObservation.basedOn: Changed items from bare `$ref` to `allOf` with context-specific example, replacing inherited `Organization/SUP001` example with correct `ServiceRequest/550e8400-e29b-41d4-a716-446655440000` -- FHIRTask.basedOn: Same fix applied - updated description to "Reference to the ServiceRequest this task fulfills" and added correct ServiceRequest example +1. Updated the examples and api spec to reflect the new handling of non-definitive results. + - Rather than using the `dataAbsentReason` field we will instead now expect it to conform with other result approaches and use a SNOMED CT code in the `valueCodeableConcept` field. +2. Make `valueCodeableConcept` a required field in the Observation schema for results. -1. Added Required Fields to FHIRTask +## Version 1.1.2 - May 18, 2026 - Additional DataAbsent Result reason -- Made `for` required - Patient beneficiary must be identified on every status update -- Made `lastModified` required - Timestamp of the status change is mandatory for audit and ordering +1. Add `haemolysed` as a valid `dataAbsentReason` when for error results. -Changes to examples/fhir/task_update_dispatched.example.json: +--- -1. Fixed task_update_dispatched Example +## Version 1.1.1 - May 12, 2026 - Add discriminator to OpenAPI specs -- Corrected `status` from `"dispatched"` (invalid FHIR value) to `"in-progress"` -- Added missing required `intent` field with value `"order"` -- Added missing required `for` field referencing `Patient/123e4567-e89b-12d3-a456-426614174000` -- Added missing required `lastModified` field with value `"2025-11-04T10:35:00Z"` -- Added `use: "official"` to identifier entry for consistency with schema example +1. This adds the discriminator field to the OpenAPI specs to allow code generation tools to typecast to the right schema, based on the 'resourceType' field. This is relevant within the Bundle of a result, where each entry can either be a DiagnosticReport, an Observation or a Communication resource. --- -## Version 1.0.6 - March 20, 2026 - Status Endpoint Method Update +## Version 1.1.0 - May 8, 2026 - Add Supplier Eligibility Check Endpoint -Changes to home-test-supplier-api.yaml +Changes to supplier-api-spec.yaml -1. Updated /test-order/status endpoint - - Changed the method from PUT to POST +1. Added /order-eligibility endpoint + - Added api spec for the eligibility check endpoint +2. Added FHIR schema files for the new endpoint + - Added ServiceRequestEligibility.json + - Added OperationOutcomeEligibility.json --- -## Version 1.0.7 - April 8, 2026 - Performer Example Update +## Version 1.0.9 - April 24, 2026 - -Changes to schemas/supplier-api-spec.yaml -Added Example to clarify required Performer fields +Change test results endpoint to use a Bundle of DiagnosticReport,Observation and Communication -1. Updated Performer Organisation - - Added Example to Performer Organisation +1. Results are now expected to be sent in a Bundle, consisting of a DiagnosticReport, an Observation and a Communication. + - Updated OpenAPI specs to reflect the new format. + - Added examples for non-reactive, reactive-with-contact, and reactive-without-contact. +2. Documentation changes to clarify and provide context around how DiagnosticReport, Observation and Communication should be populated. --- @@ -330,164 +255,239 @@ Addition of order-accepted and test-processed statuses --- -## Version 1.0.9 - April 24, 2026 - +## Version 1.0.7 - April 8, 2026 - Performer Example Update -Change test results endpoint to use a Bundle of DiagnosticReport,Observation and Communication +Changes to schemas/supplier-api-spec.yaml +Added Example to clarify required Performer fields -1. Results are now expected to be sent in a Bundle, consisting of a DiagnosticReport, an Observation and a Communication. - - Updated OpenAPI specs to reflect the new format. - - Added examples for non-reactive, reactive-with-contact, and reactive-without-contact. -2. Documentation changes to clarify and provide context around how DiagnosticReport, Observation and Communication should be populated. +1. Updated Performer Organisation + - Added Example to Performer Organisation --- -## Version 1.1.0 - May 8, 2026 - Add Supplier Eligibility Check Endpoint +## Version 1.0.6 - March 20, 2026 - Status Endpoint Method Update -Changes to supplier-api-spec.yaml +Changes to home-test-supplier-api.yaml -1. Added /order-eligibility endpoint - - Added api spec for the eligibility check endpoint -2. Added FHIR schema files for the new endpoint - - Added ServiceRequestEligibility.json - - Added OperationOutcomeEligibility.json +1. Updated /test-order/status endpoint + - Changed the method from PUT to POST --- -## Version 1.1.1 - May 12, 2026 - Add discriminator to OpenAPI specs - -1. This adds the discriminator field to the OpenAPI specs to allow code generation tools to typecast to the right schema, based on the 'resourceType' field. This is relevant within the Bundle of a result, where each entry can either be a DiagnosticReport, an Observation or a Communication resource. +## Version 1.0.5 - March 10, 2026 - Example and Required Field Corrections ---- +Changes to home-test-supplier-api.yaml: -## Version 1.1.2 - May 18, 2026 - Additional DataAbsent Result reason +1. Fixed basedOn Example Values -1. Add `haemolysed` as a valid `dataAbsentReason` when for error results. +- FHIRObservation.basedOn: Changed items from bare `$ref` to `allOf` with context-specific example, replacing inherited `Organization/SUP001` example with correct `ServiceRequest/550e8400-e29b-41d4-a716-446655440000` +- FHIRTask.basedOn: Same fix applied - updated description to "Reference to the ServiceRequest this task fulfills" and added correct ServiceRequest example ---- +1. Added Required Fields to FHIRTask -## Version 1.1.3 - June 1, 2026 - Change handling of non-definitive results +- Made `for` required - Patient beneficiary must be identified on every status update +- Made `lastModified` required - Timestamp of the status change is mandatory for audit and ordering -1. Updated the examples and api spec to reflect the new handling of non-definitive results. - - Rather than using the `dataAbsentReason` field we will instead now expect it to conform with other result approaches and use a SNOMED CT code in the `valueCodeableConcept` field. -2. Make `valueCodeableConcept` a required field in the Observation schema for results. +Changes to examples/fhir/task_update_dispatched.example.json: -## Version 1.1.4 - June 10, 2026 - Resolve OpenAPI spec Spectral validation warnings +1. Fixed task_update_dispatched Example -1. Resolved errors produced from Spectral OpenAPI spec validation. - - Adding contact field - - Adding operationIDs for all endpoints - - Adding tags - - Updating 'uri' to 'uri-reference' in the format field of the urls - - -2. Some updates to the Spectral validation, but currently still needs to be run manually +- Corrected `status` from `"dispatched"` (invalid FHIR value) to `"in-progress"` +- Added missing required `intent` field with value `"order"` +- Added missing required `for` field referencing `Patient/123e4567-e89b-12d3-a456-426614174000` +- Added missing required `lastModified` field with value `"2025-11-04T10:35:00Z"` +- Added `use: "official"` to identifier entry for consistency with schema example --- -## Version 1.1.5 - June 15, 2026 - FHIR Example File Compliance Fixes\*\* +## Version 1.0.4 - January 27, 2026 - Business-Critical Required Fields (FHIR Profiling) -Changes to examples/fhir/: +Changes to both supplier-api-spec.yaml and home-test-supplier-api.yaml: +Added Required Fields for Business Operations (FHIR Constrained Profile) -1. Added `text` narrative to all DomainResource examples (dom-6 best practice) - - Added `text.status` and `text.div` to DiagnosticReport, Observation, Communication, ServiceRequest, OperationOutcome, and Task resources across all example files - - Affected files: `observation_non_reactive`, `observation_reactive_with_contact`, `observation_reactive_without_contact`, `observation_insufficient_result`, `observation_invalid_result`, `order_servicerequest`, `ordereligibility_servicerequest`, `ordereligibility_ineligible_operationoutcome`, `operationoutcome_business_rule`, `task_update_dispatched` +1. FHIRServiceRequest Required Fields Added (supplier-api-spec.yaml only) + - Made `contained` required (minItems: 1) - Patient demographics are mandatory for order fulfillment + - Made contained Patient properties required: + - `resourceType` - Required for FHIR resource type identification + - `id` - Required for contained resource reference (#patient-1) + - `name` - Required (patient identification for order processing) + - `telecom` - Required (contact information for delivery and follow-up) + - `address` - Required (shipping address for test kit delivery) -2. Added missing `performer` and `effectiveDateTime` to Observation resources (best practice) - - All Observation resources in result bundle examples now include `performer` referencing `Organization/SUP001` - - All Observation resources now include `effectiveDateTime` - - Affected files: `observation_non_reactive`, `observation_reactive_with_contact`, `observation_reactive_without_contact`, `observation_insufficient_result`, `observation_invalid_result` +2. FHIRObservation Required Fields Added (both APIs) + - Made `basedOn` required - Links Observation to originating ServiceRequest (critical for order tracking) + - Made `valueCodeableConcept` required - The actual test result must be present (core purpose of Observation) -3. Fixed `dataAbsentReason` to include a coded value from the DataAbsentReason value set - - `observation_insufficient_result`: Added `coding` with `system: http://terminology.hl7.org/CodeSystem/data-absent-reason`, `code: not-performed` - - `observation_invalid_result`: Added `coding` with `code: error` - - Previously only `text` was present, causing a validator warning +3. FHIRTask Required Fields Added (home-test-supplier-api.yaml only) + - Made `identifier` required - Essential for tracking order status across systems -4. Fixed `get_test_results_non_reactive` searchset bundle compliance - - Changed `link.self` URL from `/results?order_uid=...` to `Bundle?identifier=...` (resource-type-qualified URL required for type checking) - - Added `search.mode: match` to the outer Bundle entry (required for searchset bundles) +4. FHIR Datatype Required Fields Added (supplier-api-spec.yaml only) + - FHIRHumanName: Made `family` required - Last name is mandatory for patient identification + - FHIRContactPoint: Made `value` required - Contact method is useless without actual contact value + - FHIRAddress: Made `line` and `postalCode` required - Minimum address information for UK deliveries -Changes to schemas/fhir-schemas/: +5. Patient Telecom Cardinality Constraint Added (supplier-api-spec.yaml only) + - Made Patient.telecom `minItems: 2` - Requires at least 2 contact points + - Updated description to clarify both phone and email are required + - **Business Rationale**: Both phone (for delivery contact) and email are essential for order fulfillment and customer communication + - **Implementation Note**: Application validation should verify one telecom has `system: 'phone'` and one has `system: 'email'` -1. Added `text` narrative to all DomainResource schema files (dom-6 best practice) - - Added `text.status` and `text.div` to `Observation.json`, `Task.json`, `OperationOutcome.json`, `ServiceRequest.json`, and `Patient.json` - - Aligns schema files with the same fixes applied to `examples/fhir/` in version 1.1.3 +--- -2. Fixed `Bundle.json` searchset compliance - - Changed `link.self` URL from `/results?order_uid=...` to `Bundle?identifier=...` (resource-type-qualified URL required for FHIR type checking) - - Added `search.mode: match` to the entry (required for searchset bundles) - - Added `text` narrative to the inner Observation resource +## Version 1.0.3 - January 27, 2026 - FHIR R4 Validation and UUID Corrections + +Changes to both supplier-api-spec.yaml and home-test-supplier-api.yaml: + +1. Fixed UUID Validation Issues in Observation Resources + - **supplier-api-spec.yaml**: Changed FHIRObservation.id example from "550e8400-e29b-41d4-a716-446655440000" to "550e8400-e29b-41d4-a716-446655440001" + - Reason: Observation ID conflicted with ServiceRequest ID causing reference validation errors + - Ensures unique UUIDs across all resources to prevent FHIR reference mismatches + - **home-test-supplier-api.yaml**: Observation.id example already correctly set to "550e8400-e29b-41d4-a716-446655440001" + - **supplier-api-spec.yaml**: Updated FHIRBundleSearchsetObservations.entry.fullUrl example to "urn:uuid:550e8400-e29b-41d4-a716-446655440001" + - Ensures Bundle fullUrl matches the Observation resource ID + - Critical for FHIR Bundle validation where fullUrl must reference the correct resource --- -## Version 1.1.6 - June 22, 2026 - Add order cancellation\*\* +## Version 1.0.2 - January 26, 2026 - Additional FHIR Compliance Updates -1. Add order cancellation process - - Allow 'revoked' as a status of the ServiceRequest - - Use 'DELETE' verb on the /order endpoint when orders are being cancelled. This allows specific errors to be defined, and helps to separate cancellation from creating a new order. - - Add documentation for rejection of further updates to cancelled orders +Changes to both supplier_api_spec.yaml and home-test-supplier-api.yaml: -2. Clarify the order eligibility check and other order states - - Remove mentions of order rejection - - Add diagram for order states - - Add documentation for order cancellation, and order acceptance (via eligibility check) +1. Added FHIRReference Reusable Schema + - Created FHIRReference component schema for proper FHIR Reference datatype + - Schema includes: + - reference (required): Literal reference, Relative, internal or absolute URL + - type (optional): Type the reference refers to (e.g., "Organization") + - display (optional): Text alternative for the resource + - Ensures proper typing for code generation (TypeScript/Java/C#) ---- +2. Updated All Reference Fields in supplier_api_spec.yaml + - ServiceRequest.subject: Changed from inline object to use FHIRReference with allOf + - ServiceRequest.requester: Changed from inline object to use FHIRReference with allOf + - ServiceRequest.performer: Changed from inline object array to FHIRReference array + - Observation.basedOn: Changed from inline object array to FHIRReference array + - Observation.subject: Changed from inline object to use FHIRReference with allOf + - Observation.performer: Changed from inline object array to FHIRReference array -## Version 1.1.7 - July 7, 2026 - Aligned API spec for APIM publication +3. Updated All Reference Fields in home-test-supplier-api.yaml + - Observation.basedOn: Changed from inline object array to FHIRReference array + - Observation.subject: Changed from inline object to use FHIRReference with allOf + - Observation.performer: Changed from inline object array to FHIRReference array + - Task.basedOn: Changed from inline object array to FHIRReference array + - Task.for: Changed from inline object to use FHIRReference with allOf + - Task.requester: Changed from inline object to use FHIRReference with allOf + - Task.owner: Changed from inline object to use FHIRReference with allOf -Changes to home-test-supplier-api.yaml: +4. Fixed FHIRTask FHIR R4 Compliance + - Added required intent field with enum values: [`unknown`, `proposal`, `plan`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option`] + - Updated required fields to include: resourceType, status, intent, basedOn -1. Add the full APIM documentation in `info.description` in accordance with the published style guides (new sections added - overview, who can use, related APIs, status, service level, technology, network access, security, errors, open source, environments, onboarding) +5. Added FHIRCodeableConcept Reusable Schema + - Created FHIRCodeableConcept component schema for proper FHIR CodeableConcept datatype + - Schema includes: + - coding (optional): Array of Coding objects with system, code, and display + - text (optional): Plain text representation of the concept + - Ensures proper typing for code generation and consistency across all coded values -2. Replace the `BearerAuth` + `NHS_Login` security schemes with a single `bearerAuth` (system-to-system consumers; no NHS Login) +6. Updated All CodeableConcept Fields in supplier-api-spec.yaml + - ServiceRequest.code: Changed from inline object to use FHIRCodeableConcept with allOf + - Observation.code: Changed from inline object to use FHIRCodeableConcept with allOf + - Observation.interpretation: Changed from inline object array to FHIRCodeableConcept array + - Observation.valueCodeableConcept: Changed from inline object to use FHIRCodeableConcept with allOf -3. Add `servers` (APIM sandbox URL) and `x-spec-publication` (Try this API disabled) +7. Updated All CodeableConcept Fields in home-test-supplier-api.yaml + - Observation.code: Changed from inline object to use FHIRCodeableConcept with allOf + - Observation.interpretation: Changed from inline object array to FHIRCodeableConcept array + - Observation.valueCodeableConcept: Changed from inline object to use FHIRCodeableConcept with allOf + - Task.statusReason: Changed from inline object to use FHIRCodeableConcept with allOf + - Task.businessStatus: Changed from inline object to use FHIRCodeableConcept with allOf ---- +8. Added Reusable FHIR Datatype Schemas + - Created FHIRCoding component schema for proper FHIR Coding datatype + - Properties: system, code, display + - Used within FHIRCodeableConcept.coding arrays + - Created FHIRIdentifier component schema for proper FHIR Identifier datatype + - Properties: system, value, use + - Used in Task.identifier arrays + - Created FHIRHumanName component schema for proper FHIR HumanName datatype + - Properties: use, family, given, text + - Used in Patient.name arrays (supplier-api-spec only) + - Created FHIRContactPoint component schema for proper FHIR ContactPoint datatype + - Properties: system, value, use + - Used in Patient.telecom arrays (supplier-api-spec only) + - Created FHIRAddress component schema for proper FHIR Address datatype + - Properties: use, type, line, city, postalCode, country + - Used in Patient.address arrays (supplier-api-spec only) -## Version 1.1.8 - July 22, 2026 - Typed CodeableConcept schemas +9. Updated All Inline Datatype Usages in supplier-api-spec.yaml + - FHIRCodeableConcept.coding: Changed from inline Coding objects to FHIRCoding array + - Patient.name (contained): Changed from inline HumanName objects to FHIRHumanName array + - Patient.telecom (contained): Changed from inline ContactPoint objects to FHIRContactPoint array + - Patient.address (contained): Changed from inline Address objects to FHIRAddress array + - OperationOutcome.issue.details: Changed from inline CodeableConcept to FHIRCodeableConcept -Changes to home-test-supplier-api.yaml: +10. Updated All Inline Datatype Usages in home-test-supplier-api.yaml + - FHIRCodeableConcept.coding: Changed from inline Coding objects to FHIRCoding array + - Task.identifier: Changed from inline Identifier objects to FHIRIdentifier array + - OperationOutcome.issue.details: Changed from inline CodeableConcept to FHIRCodeableConcept -1. Added typed CodeableConcept schemas to constrain category and -businessStatus values +Renamed supplier-api-spec.yaml for conformity - - 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"` +## Version 1.0.1 -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 +Changes to supplier_api_spec.yaml + +1. Fixed FHIR ServiceRequest Structure + - Added missing status property with FHIR-standard enum values + - Added text field to code (CodeableConcept) for human-readable representation + - Moved patient demographics from custom fields to a FHIR-compliant contained Patient resource + Changed from custom fields (firstName, lastName, phone, address.line1/line2/postcode, etc.) + To FHIR datatypes: name (HumanName), telecom (ContactPoint), address (Address with postalCode), birthDate + - Made subject a minimal Reference pointing to #patient-1 (contained resource) +2. Updated FHIRObservation + - Added text field to code (CodeableConcept) + - Removed valueQuantity (numeric results) + - Added interpretation field with FHIR ObservationInterpretation CodeableConcept + - Kept valueCodeableConcept for actual test results +3. Made /results Strictly FHIR + - Changed 200 response from custom {results: []} to FHIR Bundle (type: searchset) + - Added FHIRBundleSearchsetObservations schema + - Changed 400 error from application/problem+json to application/fhir+json with OperationOutcome + - Changed 404 error to return OperationOutcome +4. Updated All Error Responses to FHIR + - Replaced BadRequest (400) from RFC 7807 to FHIR OperationOutcome + - Replaced UnprocessableEntity (422) from RFC 7807 to FHIR OperationOutcome + - All errors now use application/fhir+json consistently +5. Made Success Responses FHIR-Compliant + - Changed POST /order 201 response from custom JSON {order_uid, order_status, estimated_delivery_date} to return the FHIR ServiceRequest resource --- -## Version 2.0.1 - August 10, 2026 - Make patient email optional +Changes to home-test-supplier-api.yaml -Changes to supplier-api-spec.yaml: +1. Fixed FHIRTask Status + - Changed status enum from custom values [`order-received`, `dispatched`, `received-at-lab`, `complete`] + - To FHIR-standard values: [`draft`, `requested`, `received`, `accepted`, `rejected`, `ready`, `cancelled`, `in-progress`, `on-hold`, `failed`, `completed`, `entered-in-error`] + > [!NOTE] + > We will map these FHIR status from our agreed status and update later + - Updated businessStatus description to indicate it holds domain-specific statuses +2. Updated FHIRObservation + - Added text field to code (CodeableConcept) + - Removed valueQuantity (numeric results) + - Added interpretation field with FHIR ObservationInterpretation CodeableConcept + - Kept valueCodeableConcept for actual test results +3. Added FHIROperationOutcome Schema + - Full FHIR-compliant OperationOutcome resource definition +4. Updated All Error Responses to FHIR + - Replaced BadRequest (400) from RFC 7807 to FHIR OperationOutcome + - Replaced Unauthorized (401) from RFC 7807 to FHIR OperationOutcome + - Replaced NotFound (404) from RFC 7807 to FHIR OperationOutcome + - All errors now use application/fhir+json consistently +5. Made Success Responses FHIR-Compliant + - Changed POST /result 201 response from custom JSON {order_uid, result_status, timestamp} to return the FHIR Observation resource -1. Make email optional in the contained Patient resource. This was a mistake confirmed during testing, as the HomeTest user journey has the patient email as an optional field. The patient's phone number is still mandatory. +---