Citing concepts — IRIs explained
Every concept on this server has a stable web address — an IRI — that can be used as a precise reference in contracts, data standards, and software. This page explains the two forms available and when to use each.
What is an IRI?
An IRI (Internationalized Resource Identifier) is simply a URL that also acts as a globally unique name for a concept. Unlike a plain label such as "Red" or "conformance criterion X", an IRI is unambiguous across organisations, languages, and time: it always refers to exactly one definition, maintained by one authority.
On this server, every published concept has both a short IRI (always the current definition) and a versioned IRI (a frozen snapshot). Both are real URLs — you can open them in a browser or fetch them in code.
URL patterns
| URL pattern | Returns |
|---|---|
| /{vocId} | Latest version of the full vocabulary (ConceptScheme) |
| /{vocId}/{conceptId} | Latest definition of a single concept short IRI |
| /{vocId}/{version} | Full vocabulary pinned to a specific version |
| /{vocId}/{version}/{conceptId} | Concept definition pinned to a specific version versioned IRI |
Example — the concept "Red" in the Colors vocabulary:
What the response tells you
Both forms return JSON-LD. The key fields are:
Short IRI response — always reflects the current published definition:
Versioned IRI response — frozen, will never change:
Guidance by audience
Use the short IRI in your documents. It is concise, readable, and links directly to the authoritative definition. Anyone who clicks it will always see the current, maintained version.
When you need to record what the definition said at a specific moment
— for example, at the time a contract was signed — add the versionIRI
from the response. This URL is permanent and will always return exactly the same content.
Recommended citation format in a document:
"As defined in https://voc.dexes.eu/example-colors/red
(version 2.0.0, retrieved [date])"
Use the short IRI as the stable identifier in your data models and APIs. It will keep working as the vocabulary evolves and always resolves to the current definition.
Use the versioned IRI when you need strict reproducibility — for example, in an audit log, a data snapshot, or a content-addressable cache key. Versioned IRIs are immutable: the content at that URL never changes.
JSON-LD: responses include a full @context with
SKOS term mappings and an @base so all concept IRIs in the document
resolve correctly. You can feed the response directly into any JSON-LD processor.
Linking between concepts: the broader,
narrower, and related fields contain concept IDs that
resolve to full IRIs via the document's @base.
The /api/vocabularies/ REST endpoints remain
available for programmatic access with filtering, pagination, and version listing.
See the API docs for details.
Version policy
Versions follow semantic versioning (MAJOR.MINOR.PATCH). A patch corrects errors in labels or definitions without changing meaning. A minor version adds new concepts. A major version indicates a breaking change — concepts may be removed or substantially redefined. When a new version is published, all short IRIs resolve to it automatically; previously issued versioned IRIs remain permanently accessible and unchanged.