id: TEDY.03 template: tool-feature module: tedy state: Proposed traces-from: [] source-refs:

• reference-editor/app/src/app/resources/map-set
• reference-editor/app/src/app/resources/_lib/map-set/model/map-set.ts
• reference-editor/app/src/app/resources/_lib/map-set/model/map-set-version.ts # scope + statistics
• reference-editor/app/src/app/resources/_lib/map-set/model/map-set-association.ts
• reference-editor/app/src/app/resources/_lib/map-set/model/map-set-concept.ts
• reference-editor/app/src/app/resources/_lib/map-set/services/map-set-lib.service.ts # GET /ts/map-sets*
• reference-editor/app/src/app/resources/map-set/services/map-set-service.ts # write /ts/map-sets*
• terminology-server (/ts/map-sets, /ts/map-set-versions, /file-importer/map-set) author: TEDY bootstrap created: 2026-08-08 updated: 2026-08-08

TEDY.03 – Map Set (Common Spec)

Description

Common specification for Map Set management in TEDY — browse, view, and author FHIR ConceptMaps over terminology-server (/ts/map-sets). A Map Set relates concepts from a source to a target (each a code system or value set, its scope) through associations (individual mappings with a relationship). This root spec owns the shared vocabulary, data + scope/association model, FHIR mapping, privileges, the full REST surface, and navigation so the child (screen) specs don’t duplicate them.

terminology-server owns persistence + the ConceptMap model + automap engine; TEDY is the React client. Derived via spec-authoring.md; the REST surface below was read from reference-editor’s map-set services and confirmed live on dev-tx.example (guest yupi).

Child specs:

• TEDY.03.1 – Map Set List
• TEDY.03.2 – Add Map Set
• TEDY.03.3 – Map Set View

Glossary Terms

Business Feature Sitemap

flowchart LR
    US["(TODO) US: manage map sets"] --> ROOT[TEDY.03]
    ROOT --> LST[TEDY.03.1 List]
    ROOT --> CRT[TEDY.03.2 Add]
    ROOT --> VIEW[TEDY.03.3 View]
    LST -->|Add map set| CRT
    LST -->|row / ID| VIEW
    CRT -->|save| VIEW
    VIEW --> ASSOC[Associations grid]
    ASSOC -->|automap / verify / unmap| ASSOC

Data Model

Shared MapSet fields

MapSetVersion fields

id, version, status, mapSet, releaseDate/expirationDate (YYYY-MM-DD), preferredLanguage, description, algorithm, identifiers, scope (MapSetScope), statistics (MapSetStatistics).

Scope + association model (Map-Set-specific)

MapSetVersion.scope                      # MapSetScope
  ├── sourceType                         # 'code-system' | 'value-set' | 'external-canonical-uri'
  ├── sourceValueSet | sourceCodeSystems[]   # MapSetResourceReference {id, version, uri}
  ├── targetType
  └── targetValueSet | targetCodeSystems[]

MapSetAssociation
  ├── source: {code, codeSystem, display}   # MapSetAssociationEntity
  ├── target: {code, codeSystem, display}
  ├── relationship                          # concept-map-relationship code
  ├── verified                              # human-verified
  ├── noMap                                 # source has no target
  └── propertyValues[]

Used value sets (resolved via @helex/tx)

FHIR Mapping (Common)

Common Rules

• Associations (the mappings) are the content; read them source-centric via .../versions/{v}/concepts (MapSetConcept + its associations) or flat via .../associations.
• Version lifecycle mirrors the other resources: draft → active → retire (dedicated endpoints, empty body, 204); editing an active version is frozen server-side.
• Batch association ops: associations-batch (bulk upsert), verify (verify/unverify sets), unmap (mark no-map), automap (background job → JobLogResponse).
• Statistics are (re)computed server-side; reload-statistics-async refreshes them.
• publisher / status / language / relationship selects use TxConceptSelect(url=…).

Shared Privileges

Common API Surface

Base /ts/map-sets unless noted. All TEDY calls go through @helex/tedy’s txApi (/txapi → dev-tx.example /api).

MapSet CRUD

List params (MapSetSearchParams): id, ids, idContains, uri, uriContains, name, nameContains, description, descriptionContains, text, textContains, publisher, versionVersion, versionStatus, versionSource, versionsDecorated, lang, spaceId, packageId, packageVersionId, plus association filters (associationSourceCode, associationSourceSystem, associationTargetCode, associationTargetSystem, … + associationsDecorated), + limit/offset/sort.

Versions + lifecycle

Associations (the mappings)

Import

Sitemap / Navigation

• /tedy/map-sets — list (TEDY.03.1)
• /tedy/map-sets/new — create (TEDY.03.2)
• /tedy/map-sets/{id} — view shell (TEDY.03.3): Summary · Metadata · Associations
• /tedy/map-sets/{id}/versions/new · /versions/{version}/edit — version form
• /tedy/map-sets/{id}/compare — version compare (placeholder, shared pattern)

Non-functional Requirements

Business Tests

1. List / view / create operate over /ts/map-sets* with the shared envelope.
2. A version carries a scope (source→target) and statistics; associations are read via .../associations or .../versions/{v}/concepts.
3. Association authoring (create/edit/verify/unmap/automap) + version lifecycle require MapSet.write; read is open on the guest dev server.
4. Publisher/status/language/relationship render via their value sets.

Traces

• traces-from: TODO user stories
• children: TEDY.03.1, TEDY.03.2, TEDY.03.3
• sibling families: TEDY.01 Code System, TEDY.02 Value Set (shared shell, version form, summary widgets, Tedy* UI)