Semantic Layers

Three concerns are routinely conflated in trade-document standards: what a term means, how a document is structured, and which rules apply in a particular context. UNVTD keeps them in separate artifacts, maintained by different parties, on different change cycles.

The general statement of that separation belongs to the vocabulary layer and is set out on the UN/CEFACT Web Vocabulary architecture page . This page covers what it means for UNVTD in particular: why conflating the layers multiplies schemas, and how the road consignment note shows the alternative.

The Three Layers

Three layers applied to the road consignment note: one vocabulary supplies meaning, one JSON Schema and JSON-LD context define structure, and many context-specific profiles supply rules

Layer	Artifact	Owned by	Changes when
Meaning	JSON-LD `@context`, resolving to the UN/CEFACT Web Vocabulary and other authoritative vocabularies	vocabulary governance	a term is added or a definition corrected — rarely
Structure	the document type’s JSON Schema	the UNVTD project	a document type gains or loses a property
Rules	a validation profile, maintained separately from the schema	whichever authority, community or counterparty imposes the requirement	a jurisdiction, programme or contract changes — often

Meaning is a dictionary entry. consignor means the same thing in a consignment note, a customs declaration and a product passport, and the vocabulary says nothing about where the term appears or whether it is mandatory.

Structure arranges terms for a purpose. A road consignment note needs a consignor, a carrier, a gross weight and a description of the goods. It borrows those meanings rather than restating them.

Rules narrow a structure for a context. An authority may require a property the schema leaves optional, or a particular identifier scheme, or a value within a range. A rule changes what counts as acceptable in that context. It does not change what any term means, and it does not create a different document type.

What Conflation Costs

Where a requirement is expressed by narrowing the schema, every context acquires a schema of its own. The effect compounds. Each jurisdiction and each programme adds its own narrowing, implementers have to support all of them, and a document that satisfies one profile fails another although every field means exactly the same thing in both.

European road transport shows the scale this reaches. The European Union electronic Freight Transport Information (eFTI) regulation covers approximately 750 data elements across 202 data subsets, the subsets arising as Member States identified national regulations that call for similar information — on average eight to ten regulations per State. The road consignment note itself exists in some 185 European variants, driven by the same national requirements. Both figures were reported to the project by participants working on eFTI (see the 30 June and 16 June 2026 minutes).

None of that proliferation reflects disagreement about what a consignor is. It is the cost of expressing context in the structural layer, and it falls on implementers: a carrier operating across several Member States faces one integration per profile instead of one integration per document.

One Document, Many Profiles

The UNVTD road consignment note is published as three artifacts and no more:

One schema — road-consignment-note-schema.yaml defines 60 properties on credentialSubject, of which 19 are required. The rest are optional because whether they are needed is a question of context, not of document type.
One context — road-consignment-note-context.json maps 87 terms to vocabulary IRIs, consignor to unece:consignor, descriptionOfGoods to unece:description, and so on. Whether those IRIs resolve is checked continuously on the linked-data status page.
One example — road-consignment-note-example.json, a valid instance.

A context-specific requirement is then expressed as a profile over that one document. An authority carrying out a roadside or border check requires the subset it is entitled to see. A Member State regulation adds a mandatory national identifier. A shipper’s contract requires handling instructions that no regulator has any interest in. Each is a set of constraints over the same schema and the same context, and not one of them is a new document type.

So 202 contexts need 202 profiles, not 202 schemas. An implementer able to issue and read the road consignment note can serve all of them, and validating against any particular profile is a separate, additive step that the issuer need not perform.

The form a profile takes is deliberately left open. JSON Schema, SHACL and procedural code can all express the same constraints, and the right choice depends on what the party applying them already runs. What matters architecturally is that the profile is a separate artifact with its own owner and its own change cycle.

Extension and Restriction

The separation works in two directions, which should not be confused.

Restriction is what a profile does. It requires more than the schema requires, or narrows an allowed value. Anything that satisfies a profile also satisfies the schema.

Extension is what an issuer may do. Properties beyond the schema may be included, and receiving systems process them or safely ignore them (see Architecture Overview). An extension carries its own meaning and should be anchored in a vocabulary like any other term.

Neither mechanism permits redefining a term. A profile that gave grossWeight a different meaning in one jurisdiction would break every verifier outside it, which is precisely the failure the layer separation exists to prevent.

Learn More

Architecture Overview · UN/CEFACT Web Vocabulary architecture · Road Consignment Note · Linked-data status · what this means for regulators: Implementation Model