id: TEDY.02 template: tool-feature module: tedy state: Proposed traces-from: [] # TODO: link terminology-editor user stories source-refs:

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

TEDY.02 – Value Set (Common Spec)

Description

Common specification for Value Set management in TEDY — browse, view, and author FHIR ValueSets over terminology-server (/ts/value-sets). Unlike a Code System (which owns its concepts), a Value Set selects concepts from one or more code systems (or other value sets) through compose rules; those rules are expanded into the concrete member list (and materialized as a snapshot). This root spec owns the shared vocabulary, data model, compose/expansion model, FHIR mapping, privileges, the full API surface, and navigation so the child (screen) specs don’t duplicate them.

terminology-server owns persistence + the FHIR + expansion engine; TEDY is the React client. Derived via spec-authoring.md (Step-1 dev-tx.example scan, Step-2 reference-editor + terminology-server reconcile). The complete REST surface below was read from reference-editor’s value-set services and confirmed live on dev-tx.example (guest yupi).

Child specs:

• TEDY.02.1 – Value Set List
• TEDY.02.2 – Add Value Set
• TEDY.02.3 – Value Set View

Glossary Terms

Business Feature Sitemap

flowchart LR
    US["(TODO) US: manage value sets"] --> ROOT[TEDY.02]
    ROOT --> LST[TEDY.02.1 List]
    ROOT --> CRT[TEDY.02.2 Add]
    ROOT --> VIEW[TEDY.02.3 View]
    LST -->|Add value set| CRT
    LST -->|row / ID| VIEW
    CRT -->|save| VIEW
    VIEW --> RULES[Rules / compose]
    VIEW --> EXP[Concepts / expansion]
    RULES -->|expand| EXP

Data Model

Shared model for list / create / view. terminology-server owns the tables; TEDY consumes the JSON envelopes.

Shared ValueSet fields

ValueSetVersion fields

Compose model (ValueSet-specific)

ValueSetVersion.ruleSet          # ValueSetVersionRuleSet {id, lockedDate, inactive}
  └── rules[]                    # ValueSetVersionRule
        ├── type                 # 'include' | 'exclude'
        ├── codeSystem           # source code system id  (rule targets a CS…)
        ├── codeSystemVersion    # CodeSystemVersionReference {id, version}
        ├── valueSet             # …or another value set…
        ├── valueSetVersion      # ValueSetVersionReference
        ├── concepts[]           # explicit ValueSetVersionConcept members
        ├── filters[]            # ValueSetRuleFilter {property, operator, value}
        └── properties[]         # property codes to carry into members

ValueSetVersionConcept (a member): { id, concept: CodeSystemConcept, display: Designation, additionalDesignations: Designation[], orderNumber, active }.

Used value sets (resolved via @helex/tx)

FHIR Mapping (Common)

Common Rules

• A value set’s members are derived by expanding the version’s ruleSet; never stored on the ValueSet root. Read the members via expansion (POST /ts/value-sets/expand) or the version snapshot.
• Snapshot vs live: prefer the stored snapshot.expansion when present (fast); fall back to a live expand for drafts / previews. Rule editing previews use expand-rule (a single unsaved rule).
• Version lifecycle mirrors Code System: draft → active → retire, via dedicated endpoints (empty body, 204); editing an active version’s metadata is frozen server-side (the reference platform rule).
• Publisher / status / language / filter-operator selects use TxConceptSelect(url=…) (dev proxies /api/tx/$expand → the reference platform FHIR).
• Concept/member display resolves from display (a Designation) → language match → the member code.

Shared Privileges

Common API Surface

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

ValueSet CRUD

List params (ValueSetSearchParams): id, ids, idContains, uri, uriContains, name, nameContains, description, descriptionContains, text, textContains, versionId, versionVersion, versionStatus, versionSource, decorated, lastVersionDecorated, lang, codeSystem, conceptCode, spaceId, packageId, packageVersionId, + limit/offset/sort.

Versions + lifecycle

Compose rules / rule-sets

Expansion

FHIR façade (read/validate/sync)

Import

Sitemap / Navigation

• /tedy/value-sets — list (TEDY.02.1)
• /tedy/value-sets/new — create (TEDY.02.2)
• /tedy/value-sets/{id} — view shell (TEDY.02.3): Summary · Metadata · Concepts (expansion) · Rules
• /tedy/value-sets/{id}/versions/new · /versions/{version}/edit — version form
• /tedy/value-sets/{id}/compare — version compare (placeholder, shared pattern)

(Standalone Router basename="/tedy"; menu routes are basename-relative.)

Non-functional Requirements

Business Tests

1. List / view / create operate over /ts/value-sets* with the shared envelope.
2. A version’s members come from expanding its ruleSet (or its snapshot), never from the root.
3. Version lifecycle (draft/activate/retire) + rule add/edit/delete require ValueSet.write; read is open on the guest dev server.
4. Publisher/status/language/filter-operator render via their value sets.

Traces

• traces-from: TODO user stories
• children: TEDY.02.1, TEDY.02.2, TEDY.02.3
• sibling family: TEDY.01 Code System (shares the shell, version form, summary widgets)