Proposal (for discussion, ahead of an RFC): making enumerations network-extensible and contextualisable in Beckn v2.1 generalised schemas (the CodedValue pattern)

[abhimail]

Status: Discussion-stage proposal. Posting here to gather feedback before drafting a formal RFC. A worked, validated implementation already exists (linked below) - however scope/naming/shape are all on the table.

TL;DR

This is about enumerations — and a network's ability to extend and contextualise them without forking a schema. Beckn v2.1 generalised extension schemas keep needing typed codes / enums — administrative areas, scheme codes, clinical specialties, deviation reasons, consent classes, and so on. Today these are modelled inconsistently (bare enums, ad-hoc strings, or a CodedValue object with no agreed rules for how a consumer finds the valid values or how a network extends them). This proposes:

1. a CodedValue shared type ({ @context, @type, code }) — a JSON-LD-native analogue of FHIR Coding; and
2. a small, normative resolution & extension convention so that a consumer can deterministically resolve a code to its value set, and a network can extend a value set without forking a schema — in a way that stays decentralised (no mandatory central vocabulary authority).

The problem

• A bare string "507" or "NO_SHOW" carries no indication of which code system it belongs to.
• Plain enums are fine for small, schema-owned, closed sets — but they can't reference externally-governed codes (LGD, PIN, ICD, SNOMED, government schemes), and they can't be extended by a network without forking the schema.
• Even where a CodedValue is used, there's no agreed answer to: given a value on the wire, where is the authoritative list, and how do I check membership? — and how does a network add its own codes for an existing class?

The pattern: CodedValue

A three-field object, using Beckn's existing JSON-LD idiom:

{ "@context": "<uri of the code system / pack>", "@type": "<ClassName>", "code": "<value>" }

Thumb rule: plain enum for small, schema-owned, operational/structural sets; CodedValue when the authority is external or the code is a domain concept other systems may align with.

The resolution & extension convention (the part that's new)

1. @type names the class, resolved via the @context document to a class IRI.
2. The value set is the vocab.jsonld co-located with that @context (siblings in a pack version) — the members whose @type is that class. context.jsonld carries term→IRI maps; vocab.jsonld carries the values.
3. The wire code equals the member's @id local name within that class (no disambiguating suffixes leaking onto the wire; a value shared by two classes is a single node typed as both).
4. Enforcement is layered: OpenAPI checks @type/@context shape; JSON-LD expands IRIs; only a vocab-aware validator / registry / network edge checks code membership.
5. Pin what you own, leave external authorities open: self-owned coded fields pin @type (const) and default-but-leave-open @context; externally-governed ones stay bare.
6. Extending without forking: a network that wants its own codes for an existing class publishes only a context.jsonld + vocab.jsonld pair (declaring its prefix, aliasing the class name, declaring members with skos:exactMatch to the base where equivalents exist) and emits its own @context. The schema structure is reused unchanged.

Why this fits Beckn's principles

• Decentralised by construction: each emitted code is self-describing via its @context; registries store native codes with no write-time normalisation, so registries stay network-sovereign and federatable. Cross-network reconciliation is an analytics-/semantic-layer concern using published skos:exactMatch maps — there is no mandatory central vocabulary authority.
• Semantic interoperability & reusability-via-abstraction: one pattern across every domain pack; the base vocabulary is a shared anchor that mappings may point to, not one they must.
• Prior art: FHIR Coding/CodeSystem, W3C SKOS (ConceptScheme/notation/exactMatch), JSON-LD @context/@type.

What already exists (for reviewers to react to)

• CodedValue shared type
• A worked, validated implementation in a health-referral schema pack: a generic ServiceCoordination layer publishes base deviation reason codes (line 104 onwards); a HealthReferral schema extends the deviation vocabulary (line 143 onwards) with referral-facing names via skos:exactMatch — exactly the "extend without forking" path. Example payloads validate.

Proposed next step

If this looks fine, I'll create an RFC — merging the CodedValue pattern and this resolution/extension convention into a single document.