AWS healthlake documentation change
Summary
Updated documentation for AWS HealthLake PATCH operation to add support for FHIRPath Patch format, restructure content with new sections, add examples for both JSON Patch and FHIRPath Patch in bundles, and update error handling and capabilities tables.
Security assessment
The changes are primarily feature enhancements and documentation restructuring. There is no evidence of addressing a specific security vulnerability or weakness. The update includes adding a new FHIRPath Patch format, expanding usage examples, and clarifying supported operations and error handling. The only potential security-related change is updating example phone numbers from masked values (************) to actual examples (555-555-5555), but this appears to be for clarity rather than addressing a security issue.
Diff
diff --git a/healthlake/latest/devguide/managing-fhir-resources-patch.md b/healthlake/latest/devguide/managing-fhir-resources-patch.md index 6a3948eaf..788d9f9e0 100644 --- a//healthlake/latest/devguide/managing-fhir-resources-patch.md +++ b//healthlake/latest/devguide/managing-fhir-resources-patch.md @@ -5 +5 @@ -UsageSupported PATCH OperationsRequest HeadersExamplesJSON Patch Path SyntaxBehaviorError HandlingCaveats +Supported PATCH FormatsUsageJSON Patch FormatFHIRPath Patch FormatRequest HeadersSample ResponseBehaviorError HandlingSummary of CapabilitiesLimitationsAdditional Resources @@ -7 +7 @@ UsageSupported PATCH OperationsRequest HeadersExamplesJSON Patch Path SyntaxBeha -# Modifying Resources with PATCH operation +# Modifying Resources with PATCH Operation @@ -9 +9 @@ UsageSupported PATCH OperationsRequest HeadersExamplesJSON Patch Path SyntaxBeha -AWS HealthLake now supports the PATCH operation for FHIR resources, enabling you to modify resources by targeting specific elements to add, replace, or delete without updating the entire resource. This operation is particularly useful for remote clients or those with limited bandwidth looking to reduce network usage. This operation is particularly useful when you need to: +AWS HealthLake supports the PATCH operation for FHIR resources, enabling you to modify resources by targeting specific elements to add, replace, or delete without updating the entire resource. This operation is particularly useful when you need to: @@ -18,0 +19 @@ AWS HealthLake now supports the PATCH operation for FHIR resources, enabling you + * Update resources as part of batch and transaction workflows @@ -21,0 +23,17 @@ AWS HealthLake now supports the PATCH operation for FHIR resources, enabling you + +## Supported PATCH Formats + +AWS HealthLake supports two standard PATCH formats: + +### JSON Patch (RFC 6902) + +Uses JSON Pointer syntax to target elements by their position in the resource structure. + +**Content-Type:** `application/json-patch+json` + +### FHIRPath Patch (FHIR R4 Specification) + +Uses FHIRPath expressions to target elements by their content and relationships, providing a FHIR-native approach to patching. + +**Content-Type:** `application/fhir+json` + @@ -24 +42 @@ AWS HealthLake now supports the PATCH operation for FHIR resources, enabling you -The PATCH operation can be invoked on FHIR resources using the PATCH HTTP method: +### Direct PATCH Operations @@ -26 +44 @@ The PATCH operation can be invoked on FHIR resources using the PATCH HTTP method -###### Supported Operations +The PATCH operation can be invoked directly on FHIR resources using the PATCH HTTP method: @@ -31 +49,7 @@ The PATCH operation can be invoked on FHIR resources using the PATCH HTTP method -## Supported PATCH Operations +### PATCH in Bundles + +PATCH operations can be included as entries within FHIR Bundles of type `batch` or `transaction`, enabling you to combine patch operations with other FHIR interactions (create, read, update, delete) in a single request. + + * **Transaction bundles** : All entries succeed or fail atomically + + * **Batch bundles** : Each entry is processed independently @@ -33 +57,6 @@ The PATCH operation can be invoked on FHIR resources using the PATCH HTTP method -HealthLake supports the following [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902#section-4) operations according to RFC 6902: + + + +## JSON Patch Format + +### Supported Operations @@ -40,3 +69,3 @@ Operation | Description -`move` | Functionally identical to a "remove" operation on the "from" location, followed immediately by an "add" operation at the target location with the value that was just removed -`copy` | Copy the value at a specified location to the target location -`test` | Test that a value at the target location is equal to a specified value +`move` | Remove a value from one location and add it to another +`copy` | Copy a value from one location to another +`test` | Test that a value at the target location equals a specified value @@ -44 +73 @@ Operation | Description -## Request Headers +### Path Syntax @@ -46,4 +75,8 @@ Operation | Description -Header | Required | Description ----|---|--- -`Content-Type` | Yes | Must be `application/json-patch+json` -`If-Match` | No | Version-specific conditional update using ETag +JSON Patch uses JSON Pointer syntax (RFC 6901): + +Path Example | Description +---|--- +`/name/0/family` | First name's family element +`/telecom/-` | Append to telecom array +`/active` | Root-level active element +`/address/0/line/1` | Second line of first address @@ -51 +84 @@ Header | Required | Description -## Examples +### Examples @@ -53 +86 @@ Header | Required | Description -###### PATCH Request with Multiple Operations +###### Direct JSON Patch Request with Multiple Operations @@ -71 +104 @@ Header | Required | Description - "value": "************", + "value": "555-555-5555", @@ -96 +129 @@ Header | Required | Description -###### PATCH Request with Single Operation +###### Direct JSON Patch Request with Single Operation @@ -110 +143,110 @@ Header | Required | Description -###### Sample Response +###### JSON Patch in Bundle + +Use a Binary resource containing the base64-encoded JSON Patch payload: + + + { + "resourceType": "Bundle", + "type": "transaction", + "entry": [{ + "resource": { + "resourceType": "Binary", + "contentType": "application/json-patch+json", + "data": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL2JpcnRoRGF0ZSIsInZhbHVlIjoiMTk5MC0wMS0wMSJ9XQ==" + }, + "request": { + "method": "PATCH", + "url": "Patient/123" + } + }] + } + +## FHIRPath Patch Format + +### Supported Operations + +Operation | Description +---|--- +`add` | Add a new element to a resource +`insert` | Insert an element at a specific position in a list +`delete` | Remove an element from a resource +`replace` | Replace the value of an existing element +`move` | Reorder elements within a list + +### Path Syntax + +FHIRPath Patch uses FHIRPath expressions, supporting: + + * **Index-based access** : `Patient.name[0]` + + * **Filtering with`where()`**: `Patient.name.where(use = 'official')` + + * **Boolean logic** : `Patient.telecom.where(system = 'phone' and use = 'work')` + + * **Subsetting functions** : `first()`, `last()` + + * **Existence checks** : `exists()`, `count()` + + * **Polymorphic navigation** : `Observation.value` + + + + +### Examples + +###### Direct FHIRPath Patch Request + + + PATCH [base]/Patient/123 + Content-Type: application/fhir+json + Authorization: ... + + { + "resourceType": "Parameters", + "parameter": [{ + "name": "operation", + "part": [ + { "name": "type", "valueCode": "add" }, + { "name": "path", "valueString": "Patient" }, + { "name": "name", "valueString": "birthDate" }, + { "name": "value", "valueDate": "1990-01-01" } + ] + }] + } + +###### FHIRPath Patch in Bundle + +Use a Parameters resource as the entry resource with `method: PATCH`: + + + { + "resourceType": "Bundle", + "type": "transaction", + "entry": [{ + "resource": { + "resourceType": "Parameters", + "parameter": [{ + "name": "operation", + "part": [ + { "name": "type", "valueCode": "add" }, + { "name": "path", "valueString": "Patient" }, + { "name": "name", "valueString": "birthDate" }, + { "name": "value", "valueDate": "1990-01-01" } + ] + }] + }, + "request": { + "method": "PATCH", + "url": "Patient/123" + } + }] + } + +## Request Headers + +Header | Required | Description +---|---|--- +`Content-Type` | Yes | `application/json-patch+json` for JSON Patch or `application/fhir+json` for FHIRPath Patch