Vocabulary

A Vocabulary is a code list. It is either yours, in which case it carries its codes, or somebody else’s, in which case you reference it where it already lives and say what you use it for.

Fields

Field	Type
resourceType	string, required	Always Vocabulary.
id	string, required	Short identifier, unique among your vocabularies.
url	URL, required	The vocabulary’s identity.
version	string, required	The vocabulary’s version. For an external one, the version you use.
system	string, required	Who defines it. internal for your own; otherwise the defining authority.
name	string, required	Human-readable name.
description	string, optional	What the codes cover.
codes	array, optional	The codes themselves, for a vocabulary you define.
mapsTo	array, optional	Alignments to external terminologies.
publisher	string, optional	Who publishes it, when it differs from the ontology.

Each entry in codes:

Field	Type
code	string, required	The value that appears in data.
display	string, required	The label a person reads.
definition	string, optional	What the code means, where the label is not enough.

Your own vocabulary

Codes inline, and an alignment to whatever a consumer is more likely to already handle:

{
  "resourceType": "Vocabulary",
  "id": "exampleorg-invoice-status",
  "url": "https://api.example.org/codes/invoice-status",
  "version": "1.0.0",
  "system": "internal",
  "name": "ExampleOrg invoice status",
  "description": "List of invoice status codes.",
  "codes": [
    { "code": "OPEN", "display": "Open" },
    { "code": "PAID", "display": "Paid" },
    { "code": "VOID", "display": "Void" },
    { "code": "UNKNOWN", "display": "Unknown" }
  ],
  "mapsTo": [
    {
      "system": "http://hl7.org/fhir",
      "schema": "http://hl7.org/fhir/ValueSet/invoice-status",
      "mapping": "https://ours.example.org/mappings/invoice-status-to-fhir-value-set.json",
      "type": "one-to-one"
    }
  ]
}

Somebody else’s vocabulary

Reference it at the authority’s own URL and leave codes out. Republishing ISO 4217 would create a second copy that drifts, and the point of using a published code list is that there is one of it.

{
  "resourceType": "Vocabulary",
  "id": "iso-4217",
  "url": "https://www.iso.org/iso-4217-currency-codes.html",
  "version": "2015",
  "system": "https://www.iso.org",
  "name": "ISO 4217 currency codes",
  "description": "List of currency codes."
}

Listing an external vocabulary is still worth doing. It tells a consumer which code lists your data draws on, which is the thing they would otherwise have to infer from the values.

Neither codes nor an alignment

A vocabulary with no codes and no mapsTo says only that it exists. A consumer cannot validate against it, cannot translate it, and cannot look it up. That is a warning rather than an error, because an external vocabulary at a stable, public URL is genuinely self-describing to a human, but it is worth a second look before you publish it.

Vocabularies are also JSON Schema

Every vocabulary is served a second time as an ordinary JSON Schema enumeration, beside itself with .schema.json in place of .json. A model binds a property to it with a plain $ref, so an off-the-shelf validator enforces your codes without knowing what OURS is.

Schemas covers the derivation and where the file goes.