add draft for FHIR $add-mapping operation by galemsky-hs · Pull Request #9 · Aidbox/aidbox-hl7v2-example

galemsky-hs · 2026-02-03T07:07:51Z

No description provided.

galemsky-hs

Very rough so far

galemsky-hs

It's much better already! But it raises several design questions we need to address

galemsky-hs · 2026-02-04T07:05:15Z

+
+The `$add-mappings` operation adds one or more mappings to a ConceptMap resource without returning the full resource content.
+
+The [$add](https://hl7.org/fhir/R5/resource-operation-add.html) operation supports only Group and List resources and returns the modified resource. For large ConceptMap resources, returning the full content is not practical.


I think this should be moved to the "rationale" section that will not be part of the spec, since it's not really a part of it and I believe it won't be present on the hl7.org page of the operation.

galemsky-hs · 2026-02-04T07:07:11Z

+
+The operation is atomic: if any mapping causes an error, no mappings are added.
+
+All ConceptMap elements outside of `group` are ignored.


I think we can make the language closer to the $add spec:

The server SHALL ignore all elements except for the relevant array (e.g., Group.member or List.entry).

galemsky-hs · 2026-02-04T07:12:01Z

+
+- If a mapping does not exist, it is added.
+- If a mapping exists with identical values for all fields, no action is taken.
+- If a mapping exists with different values (e.g., different `relationship`, `display`, or `comment`), the server SHALL return an error.


Hmmmmm... So if there's a collision, it will require a manual intervention, since we don't have $remove-mapping or $insert-mapping operations. It's worth to discuss it

It looks like the standard approach for adding multiple elements is making a Bundle which already has the property: type = transaction/batch. It will solve the problem, but will make the solution less elegant. Need to discuss as well

Add specs:

the current one

add-mapping that behaves like merge ("This instance-level operation merges array entries into an existing ("target") resource, based on values from a supplied ("input") resource, ignoring any values that are already present in the target. ")

merge-mapping that behaves like merge

galemsky-hs · 2026-02-04T07:12:41Z

+
+The [$add](https://hl7.org/fhir/R5/resource-operation-add.html) operation supports only Group and List resources and returns the modified resource. For large ConceptMap resources, returning the full content is not practical.
+
+The server SHALL add mappings from the input `group` elements. Two mappings are considered the same if they share the same `group.source`, `group.target`, `element.code`, and `target.code`.


"SHALL add all mappings" I think

galemsky-hs · 2026-02-04T07:14:00Z

@@ -0,0 +1,96 @@
+# Operation $add-mappings on ConceptMap
+
+The `$add-mappings` operation adds one or more mappings to a ConceptMap resource without returning the full resource content.


Looks like it's better to keep singular name ($add-mapping) even though it can insert many. Looks more aligned with fhir IMO

galemsky-hs · 2026-02-04T07:16:46Z

+- If a mapping exists with different values (e.g., different `relationship`, `display`, or `comment`), the server SHALL return an error.
+- If a `group` with the specified `source` and `target` does not exist, it is created.
+
+The operation is atomic: if any mapping causes an error, no mappings are added.


Hm, need to check if it aligns with fhir standards

galemsky-hs · 2026-02-04T07:17:02Z

+
+All ConceptMap elements outside of `group` are ignored.
+
+URL: [base]/ConceptMap/[id]/$add-mappings


Should be moved to the top

galemsky-hs · 2026-02-04T07:17:17Z

+
+URL: [base]/ConceptMap/[id]/$add-mappings
+
+This is an idempotent operation.


Can merge atomic property and this claim into 1 line

- Simplify $add-mapping to merge semantics - Rename $add-mappings to $add-mapping - Ignore duplicates instead of returning conflict - Remove atomicity requirement

- Add OperationDefinition JSON targeting FHIR R6 - Move rationale (why not $add) to separate section - Use FHIR conformance language ("SHALL ignore") - Reorder sections to match FHIR spec structure - Mark as not idempotent

- Restructure document to contain both $add-mapping and $remove-mapping - Add shared introduction and rationale section - Add complete $remove-mapping operation with parameters, examples, and formal OperationDefinition - Move rationale to document top, demote Examples/Formal Definition to subsections - Align with FHIR style conventions

mapping match criteria

$remove-mapping drafts

…r $replace-mapping

galemsky-hs commented Feb 3, 2026

View reviewed changes

galemsky-hs commented Feb 4, 2026

View reviewed changes

galemsky-hs force-pushed the add-mapping-fhir-operation branch from dba6eb5 to d8b1735 Compare February 12, 2026 12:27

Seryiza and others added 11 commits February 18, 2026 15:14

add draft for FHIR $add-mapping operation

bb0bbbd

improve draft for $add-mappings (FHIR operation)

e3fb292

improve draft for $add-mapping operation

03c4ee3

- Simplify $add-mapping to merge semantics - Rename $add-mappings to $add-mapping - Ignore duplicates instead of returning conflict - Remove atomicity requirement

$add-mapping draft: use fully-qualified FHIR dot-notation paths for

bdd01d6

mapping match criteria

docs: improve draft for FHIR $add-mapping, $remove-mapping operations

fb330e8

docs: remove "not an idempotent operation" for $add-mapping,

f4c70e2

$remove-mapping drafts

$add-mapping: add error about multiple matched groups

b4aec63

Add $update-mapping operation

78eee80

Update operations

b7fd53f

galemsky-hs force-pushed the add-mapping-fhir-operation branch from 7828a23 to b7fd53f Compare February 18, 2026 09:14

galemsky-hs added 4 commits February 18, 2026 15:34

Make errors easier to read

11e17e0

Change $replace-element with update-type=replace-element

b3a7004

Remove noMap conflict from $update-mapping

68a9f9a

Add auto-resolve semantic to $update-mapping instead of update-type o…

d1d0f41

…r $replace-mapping

galemsky-hs force-pushed the add-mapping-fhir-operation branch from 33aca9a to d1d0f41 Compare February 18, 2026 13:18

Format a bit

83aae34


		The `$add-mappings` operation adds one or more mappings to a ConceptMap resource without returning the full resource content.

		The [$add](https://hl7.org/fhir/R5/resource-operation-add.html) operation supports only Group and List resources and returns the modified resource. For large ConceptMap resources, returning the full content is not practical.


		The operation is atomic: if any mapping causes an error, no mappings are added.

		All ConceptMap elements outside of `group` are ignored.


		The [$add](https://hl7.org/fhir/R5/resource-operation-add.html) operation supports only Group and List resources and returns the modified resource. For large ConceptMap resources, returning the full content is not practical.

		The server SHALL add mappings from the input `group` elements. Two mappings are considered the same if they share the same `group.source`, `group.target`, `element.code`, and `target.code`.

		@@ -0,0 +1,96 @@
		# Operation $add-mappings on ConceptMap

		The `$add-mappings` operation adds one or more mappings to a ConceptMap resource without returning the full resource content.


		All ConceptMap elements outside of `group` are ignored.

		URL: [base]/ConceptMap/[id]/$add-mappings


		URL: [base]/ConceptMap/[id]/$add-mappings

		This is an idempotent operation.

Conversation

galemsky-hs commented Feb 3, 2026

Uh oh!

galemsky-hs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

galemsky-hs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants