Update operations

Author: galemsky-hs

docs/v2-to-fhir-spec/add-mapping-fhir-operation.md

@@ -1,28 +1,30 @@
 # ConceptMap Mapping Operations
 
-This page defines three operations for managing individual mappings within large [ConceptMap](https://hl7.org/fhir/conceptmap.html) resources: `$add-mapping`, `$update-mapping`, and `$remove-mapping`.
+This page defines four operations for managing individual mappings within large [ConceptMap](https://hl7.org/fhir/conceptmap.html) resources: `$add-mapping`, `$update-mapping`, `$remove-mapping`, and `$replace-element`.
 
 ## Background
 
 The existing [$add](https://fhir.hl7.org/fhir/resource-operation-add.html) and [$remove](https://fhir.hl7.org/fhir/resource-operation-remove.html) operations (see [Operations for Large Resources](https://www.hl7.org/fhir/operations-for-large-resources.html)) return the modified resource and use structural matching on array entries. ConceptMap resources may contain thousands of mappings and require matching on a domain-specific composite key, so these operations return an OperationOutcome instead.
 
-For all three operations, only `group` elements in the input are processed; all other elements are ignored.
+For all four operations, only `group` elements in the input are processed; all other elements are ignored.
 
 ## Matching Algorithm
 
-All three operations use the same matching algorithm. Two mappings match when they have identical values for `group.source`, `group.target`, `element.code`, and `element.target.code`.
+`$add-mapping`, `$update-mapping`, and `$remove-mapping` use target-level matching. Two mappings match when they have identical values for `group.source`, `group.target`, `element.code`, and `element.target.code`.
 
 For `noMap` entries (no `element.target`), matching uses `group.source`, `group.target`, and `element.code` only.
 
 Only these fields are compared; other element properties such as `display` or `relationship` are not considered. To update an existing mapping's non-key properties, use `$update-mapping`.
 
+`$replace-element` uses element-level matching: two elements match when they have identical values for `group.source`, `group.target`, and `element.code`. All targets and `noMap` state for the matched element are replaced atomically.
+
 ## $add-mapping Operation
 
 The `$add-mapping` operation merges mappings into a ConceptMap, skipping any that already exist.
 
 URL: [base]/ConceptMap/[id]/$add-mapping
 
-The server SHALL add each input mapping that does not already exist. Existing mappings (same match key) are skipped; the server SHOULD report skipped entries in the OperationOutcome. If no `group` exists for the given `source` and `target`, one is created.
+The server SHALL add each input mapping that does not already exist. If an input mapping already exists (same match key), the server ignores it by default (`if-exists=ignore`) and SHOULD report skipped entries in the OperationOutcome; set `if-exists=fail` to return an error instead. If no `group` exists for the given `source` and `target`, one is created.
 
 It is an error to add a mapping with `target` for a source code that already has `noMap=true`, or to add `noMap=true` for a code that already has target mappings.
 It is also an error if the ConceptMap contains more than one group with the same `source` and `target` as an input mapping, since the target group is ambiguous.
@@ -35,6 +37,7 @@ Clients MAY supply an `If-Match` header; servers SHALL reject the request if the
 | Name | Cardinality | Type | Documentation |
 |------|-------------|------|---------------|
 | mappings | 1..1 | ConceptMap | Only `group` elements are processed |
+| if-exists | 0..1 | code | Behaviour when an input mapping already exists: `ignore` (default) — skip with SHOULD-report; `fail` — return an error |
 
 **Out Parameters**
 
@@ -100,6 +103,46 @@ Content-Type: application/fhir+json
 }
 ```
 
+Request: add GLUC → LOINC, failing if it already exists (`if-exists=fail` passed as query parameter).
+
+```http
+POST /ConceptMap/lab-codes-to-loinc/$add-mapping?if-exists=fail HTTP/1.1
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "ConceptMap",
+  "group": [{
+    "source": "http://example.org/local-codes",
+    "target": "http://loinc.org",
+    "element": [{
+      "code": "GLUC",
+      "display": "Glucose",
+      "target": [{
+        "code": "2345-7",
+        "display": "Glucose [Mass/volume] in Serum or Plasma",
+        "relationship": "equivalent"
+      }]
+    }]
+  }]
+}
+```
+
+Error response: mapping already exists.
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "OperationOutcome",
+  "issue": [{
+    "severity": "error",
+    "code": "duplicate",
+    "diagnostics": "Mapping already exists for code 'GLUC' → '2345-7' in group (source=http://example.org/local-codes, target=http://loinc.org)"
+  }]
+}
+```
+
 ### Formal Definition
 
 ```json
@@ -127,6 +170,14 @@ Content-Type: application/fhir+json
       "documentation": "ConceptMap containing mappings to add. Only group elements are processed.",
       "type": "ConceptMap"
     },
+    {
+      "name": "if-exists",
+      "use": "in",
+      "min": 0,
+      "max": "1",
+      "documentation": "Behaviour when an input mapping already exists: 'ignore' (default) — skip with SHOULD-report; 'fail' — return an error.",
+      "type": "code"
+    },
     {
       "name": "return",
       "use": "out",
@@ -149,7 +200,7 @@ The server SHALL replace each matching mapping with the input values; properties
 The server SHOULD report the number of mappings updated and added in the OperationOutcome.
 
 Like `$add-mapping`, it is an error to add a mapping with `target` for a source code that already has `noMap=true`, or to add `noMap=true` for a code that already has target mappings.
-It is also an error if the ConceptMap contains more than one group with the same `source` and `target` as an input mapping, since the target group is ambiguous. 
+It is also an error if the ConceptMap contains more than one group with the same `source` and `target` as an input mapping, since the target group is ambiguous.
 In either case the server SHALL return an OperationOutcome with `severity=error` and `code=business-rule`.
 
 Clients MAY supply an `If-Match` header; servers SHALL reject the request if the ETag does not match. See [Managing Resource Contention](https://hl7.org/fhir/http.html#concurrency).
@@ -264,7 +315,7 @@ The `$remove-mapping` operation removes mappings from a ConceptMap.
 
 URL: [base]/ConceptMap/[id]/$remove-mapping
 
-The server SHALL remove all mappings that match the input entries, across all groups in the ConceptMap. If no matching mapping exists for an input entry, the server SHALL ignore it.
+The server SHALL remove all mappings that match the input entries. If no matching mapping exists for an input entry, the server SHALL ignore it. If an input entry matches entries across more than one group, the server SHALL return an error by default (`on-multiple-match=fail`); set `on-multiple-match=remove-all` to remove from all matching groups.
 
 Clients MAY supply an `If-Match` header; servers SHALL reject the request if the ETag does not match. See [Managing Resource Contention](https://hl7.org/fhir/http.html#concurrency).
 
@@ -273,6 +324,7 @@ Clients MAY supply an `If-Match` header; servers SHALL reject the request if the
 | Name | Cardinality | Type | Documentation |
 |------|-------------|------|---------------|
 | mappings | 1..1 | ConceptMap | Only `group` elements are processed |
+| on-multiple-match | 0..1 | code | Behaviour when an input entry matches entries across more than one group: `fail` (default) — return an error; `remove-all` — remove from all matching groups |
 
 **Out Parameters**
 
@@ -319,6 +371,43 @@ Content-Type: application/fhir+json
 }
 ```
 
+Request: remove the GLUC → 2345-7 mapping from all groups when duplicate groups exist.
+
+```http
+POST /ConceptMap/lab-codes-to-loinc/$remove-mapping?on-multiple-match=remove-all HTTP/1.1
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "ConceptMap",
+  "group": [{
+    "source": "http://example.org/local-codes",
+    "target": "http://loinc.org",
+    "element": [{
+      "code": "GLUC",
+      "target": [{
+        "code": "2345-7"
+      }]
+    }]
+  }]
+}
+```
+
+Response: mapping removed from all matching groups.
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "OperationOutcome",
+  "issue": [{
+    "severity": "information",
+    "code": "informational",
+    "diagnostics": "2 mappings removed"
+  }]
+}
+```
+
 ### Formal Definition
 
 ```json
@@ -346,6 +435,116 @@ Content-Type: application/fhir+json
       "documentation": "ConceptMap containing mappings to remove. Only group elements are processed.",
       "type": "ConceptMap"
     },
+    {
+      "name": "on-multiple-match",
+      "use": "in",
+      "min": 0,
+      "max": "1",
+      "documentation": "Behaviour when an input entry matches entries across more than one group: 'fail' (default) — return an error; 'remove-all' — remove from all matching groups.",
+      "type": "code"
+    },
+    {
+      "name": "return",
+      "use": "out",
+      "min": 1,
+      "max": "1",
+      "documentation": "Outcome of the operation",
+      "type": "OperationOutcome"
+    }
+  ]
+}
+```
+
+## $replace-element Operation
+
+The `$replace-element` operation atomically replaces entire elements (all targets and `noMap` state) in a ConceptMap.
+
+URL: [base]/ConceptMap/[id]/$replace-element
+
+The server SHALL match each input element by `(group.source, group.target, element.code)` and replace the entire element with the input values. If no matching element exists, the server SHALL add it. If no `group` exists for the given `source` and `target`, one is created. The server SHOULD report the number of elements replaced and added in the OperationOutcome.
+
+Unlike `$add-mapping` and `$update-mapping`, no `noMap` conflict check is performed — the input element replaces whatever was previously there, enabling atomic transitions between mapped and `noMap` states.
+
+It is an error if the ConceptMap contains more than one group with the same `source` and `target` as an input element, since the target group is ambiguous. The server SHALL return an OperationOutcome with `severity=error` and `code=business-rule`.
+
+Clients MAY supply an `If-Match` header; servers SHALL reject the request if the ETag does not match. See [Managing Resource Contention](https://hl7.org/fhir/http.html#concurrency).
+
+**In Parameters**
+
+| Name | Cardinality | Type | Documentation |
+|------|-------------|------|---------------|
+| elements | 1..1 | ConceptMap | Only `group` elements are processed |
+
+**Out Parameters**
+
+| Name | Cardinality | Type | Documentation |
+|------|-------------|------|---------------|
+| return | 1..1 | OperationOutcome | Outcome of the operation |
+
+### Example
+
+Request: atomically transition GLUC from a target mapping to `noMap`.
+
+```http
+POST /ConceptMap/lab-codes-to-loinc/$replace-element HTTP/1.1
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "ConceptMap",
+  "group": [{
+    "source": "http://example.org/local-codes",
+    "target": "http://loinc.org",
+    "element": [{
+      "code": "GLUC",
+      "noMap": true
+    }]
+  }]
+}
+```
+
+Response: element replaced.
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/fhir+json
+
+{
+  "resourceType": "OperationOutcome",
+  "issue": [{
+    "severity": "information",
+    "code": "informational",
+    "diagnostics": "1 element replaced"
+  }]
+}
+```
+
+### Formal Definition
+
+```json
+{
+  "resourceType": "OperationDefinition",
+  "id": "ConceptMap-replace-element",
+  "url": "http://hl7.org/fhir/OperationDefinition/ConceptMap-replace-element",
+  "version": "6.0.0",
+  "name": "ReplaceElement",
+  "title": "Replace elements in a ConceptMap",
+  "status": "draft",
+  "kind": "operation",
+  "affectsState": true,
+  "code": "replace-element",
+  "resource": ["ConceptMap"],
+  "system": false,
+  "type": false,
+  "instance": true,
+  "parameter": [
+    {
+      "name": "elements",
+      "use": "in",
+      "min": 1,
+      "max": "1",
+      "documentation": "ConceptMap containing elements to replace. Only group elements are processed.",
+      "type": "ConceptMap"
+    },
     {
       "name": "return",
       "use": "out",
@@ -360,4 +559,4 @@ Content-Type: application/fhir+json
 
 ## Notes
 
-Multiple groups with the same `source` and `target` within a single ConceptMap are permitted but discouraged. When different mapping subsets require different `unmapped` handling, they SHOULD be modeled as separate ConceptMap resources — subsets are a concept map-level concern.
+Multiple groups with the same `source` and `target` within a single ConceptMap are permitted but discouraged. When different mapping subsets require different `unmapped` handling, they SHOULD be modeled as separate ConceptMap resources — subsets are a concept map-level concern.