From 55597126956e21d3b837a8503bc70c60217e3285 Mon Sep 17 00:00:00 2001 From: Thomas-Boyle Date: Fri, 6 Mar 2026 12:40:56 +0000 Subject: [PATCH 1/2] Modified Immunisation FHIR API documentation to include target disease search functionality - Updated the API specification to clarify the use of the new `target-disease` parameter alongside `-immunization.target` for searching vaccination records. - Improved descriptions for both parameters to ensure clear guidelines on their usage and mutual exclusivity. - Added examples and links to supported target disease codes to aid developers in implementing the search feature effectively. - Ensured consistency in error handling documentation for invalid parameter combinations. --- specification/immunisation-fhir-api.yaml | 45 +++++++++++++++--------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/specification/immunisation-fhir-api.yaml b/specification/immunisation-fhir-api.yaml index 17164e8a5..b3529b0f7 100644 --- a/specification/immunisation-fhir-api.yaml +++ b/specification/immunisation-fhir-api.yaml @@ -1314,9 +1314,10 @@ paths: ## Overview Use this interaction to search for a patient's vaccination records using - their NHS number and DiseaseType. You can request the patient's - vaccination history for one or more specified 'disease types'. You may - limit the vaccination records by specifying date criteria, for example + their NHS number and either vaccination type (-immunization.target) or + target disease (target-disease). You can request the patient's vaccination + history for one or more disease types, or by SNOMED target disease code(s). + You may limit the vaccination records by specifying date criteria, for example if you only need to know about vaccinations administered in the last 12 months. @@ -1358,7 +1359,7 @@ paths: body | | Bad Request | Didn't pass required fields - `patient.identifier` or `-immunization.target` | HTTP Status + `patient.identifier` or `-immunization.target` or `target-disease` | HTTP Status 400 Bad Request | parameters: - $ref: "#/components/parameters/CorrelationID" @@ -1391,7 +1392,8 @@ paths: A POST search allows you to supply some or all parameters in the body of the request should you need to do so. It offers the same search functionality as the GET - search interaction. + search interaction, including search by vaccination type + (-immunization.target) or by target disease (target-disease). ## Sandbox testing @@ -1420,7 +1422,7 @@ paths: body | | Bad Request | Didn't pass required fields - `patient.identifier` or `-immunization.target` | HTTP Status + `patient.identifier` or `-immunization.target` or `target-disease` | HTTP Status 400 Bad Request | parameters: - $ref: "#/components/parameters/CorrelationID" @@ -4248,7 +4250,9 @@ components: type: string description: > Specific procedures, disorders, diseases, infections or - organisms (vaccination type). Cannot be used with target-disease. + organisms (vaccination type). Cannot be used with target-disease or + identifier. For patient search, one of -immunization.target or + target-disease is required. example: FLU enum: - 3IN1 @@ -4265,10 +4269,14 @@ components: target-disease: type: string description: > - FHIR-compliant search by target disease. Format system|code with - system http://snomed.info/sct and code a SNOMED code from the - supported target disease list. Comma-separated for multiple (OR). - Cannot be used with -immunization.target. + Search by target disease using FHIR-compliant SNOMED codes. Format + system|code with system http://snomed.info/sct and code from the + [supported target disease list](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/vaccinations/coding-for-vaccination-disease-types#how-this-applies-to-vaccinations-submitted-to-the-api). + Comma-separated for multiple (OR). Cannot be used with + -immunization.target or identifier. For patient search, one of + -immunization.target or target-disease is required. Returns + vaccinations that protect against the given disease(s), including + combination vaccines (e.g. MMR, MMRV for measles). example: "http://snomed.info/sct|14189004" "-date.from": type: string @@ -4381,11 +4389,16 @@ components: in: query name: target-disease description: | - FHIR-compliant search by target disease. Value must be in the format system|code where - system MUST be http://snomed.info/sct and code MUST be a SNOMED code from the supported - target disease list. Multiple comma-separated values allowed (OR). Cannot be used with - -immunization.target or identifier. Returns vaccinations that protect against the given - disease(s), including combination vaccines (e.g. MMR, MMRV for measles). + Search by target disease using FHIR-compliant SNOMED codes. Use this parameter to + retrieve vaccinations that protect against specific disease(s), including combination + vaccines (e.g. MMR or MMRV when searching for measles). + + Format: system|code where system MUST be http://snomed.info/sct and code MUST be + a SNOMED code from the [supported target disease list](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/vaccinations/coding-for-vaccination-disease-types#how-this-applies-to-vaccinations-submitted-to-the-api). + Multiple comma-separated values are allowed (OR). Cannot be used with + -immunization.target or identifier. For patient search, one of -immunization.target + or target-disease is required. Invalid or unsupported codes may result in + OperationOutcome entries in the response or 400 when all values are invalid. required: false schema: type: string From 5492a80523958af25ee0f2c03aad0875d0553c8b Mon Sep 17 00:00:00 2001 From: Thomas-Boyle Date: Fri, 6 Mar 2026 15:07:25 +0000 Subject: [PATCH 2/2] Refine Immunisation FHIR API documentation for target disease parameter - Updated descriptions for the `target-disease` parameter to clarify its expression format as `system|code`. - Ensured consistency in language throughout the documentation to enhance clarity for developers implementing the search functionality. - Maintained links to the supported target disease list for reference. --- specification/immunisation-fhir-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/immunisation-fhir-api.yaml b/specification/immunisation-fhir-api.yaml index b3529b0f7..f732a57f3 100644 --- a/specification/immunisation-fhir-api.yaml +++ b/specification/immunisation-fhir-api.yaml @@ -4269,8 +4269,8 @@ components: target-disease: type: string description: > - Search by target disease using FHIR-compliant SNOMED codes. Format - system|code with system http://snomed.info/sct and code from the + Search by target disease using FHIR-compliant SNOMED codes. Expressed as + `system|code` with system `http://snomed.info/sct` and code from the [supported target disease list](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/vaccinations/coding-for-vaccination-disease-types#how-this-applies-to-vaccinations-submitted-to-the-api). Comma-separated for multiple (OR). Cannot be used with -immunization.target or identifier. For patient search, one of @@ -4393,7 +4393,7 @@ components: retrieve vaccinations that protect against specific disease(s), including combination vaccines (e.g. MMR or MMRV when searching for measles). - Format: system|code where system MUST be http://snomed.info/sct and code MUST be + Expressed as `system|code` where system MUST be `http://snomed.info/sct` and code MUST be a SNOMED code from the [supported target disease list](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/vaccinations/coding-for-vaccination-disease-types#how-this-applies-to-vaccinations-submitted-to-the-api). Multiple comma-separated values are allowed (OR). Cannot be used with -immunization.target or identifier. For patient search, one of -immunization.target