Semantic Model Walkthrough

This walkthrough builds one concrete use case end to end: an organization (Acme Corp) issues employee credentials and later verifies a subset of them. Acme issues two credentials to its people, an Employee credential as an SD-JWT VC and a Business Card as an mdoc, and stands up a standalone verifier that asks a wallet to present claims from both in a single request.

The OpenID4VCI issuance and OpenID4VP verification flows are the same ones documented in the OpenID4VCI and OpenID4VP guides. The issuer design and verifier DCQL are derived from a shared semantic model, so the issued credential and requested credential agree on attribute identity by construction.

The pages that follow take you from modeling your world to the REST calls that drive the flow. They focus on the public EDK REST API and the JSON it exchanges. VDX presents the same authoring operations through a guided UI, so an operator can build and govern the model without writing requests by hand.

The mental model

The naive way to stand up an issuer and a verifier is to hand-author both wire forms:

• The issuer POSTs a credential design with a literal claims[] array. Each claim carries its own path, selective-disclosure policy, label, and ordering, all typed by hand.
• The verifier POSTs a DCQL query with a literal credentials[] array and claim paths typed independently of the issuer.

That works for a single credential, but it does not scale across an organization. There is no shared definition of what given_name means, so issuer and verifier fields can drift apart. Selective-disclosure policy, data classification, legal basis, and retention are retyped on every design. Nothing records which business terms a design or query consumed.

The enterprise semantic model inverts this. A canonical, organization-owned model is authored once, and issuer designs and verifier DCQL are renderings derived from it. The model is the source of truth; the wire forms are outputs.

The four tiers

The model is a layered authoring stack. Each tier is authoritative for the tier above it, narrowing what downstream tiers admit and never widening it.

• L1 Data Domain is the canonical layer. It describes the organization's world with ObjectType records, their BusinessTerm trees, and first-class RelationshipType records. Object types are either PREDEFINED party types such as natural_person, address, and organization, or SPECIALIZATION subtypes that add business terms. A data domain is owned by a Party, versioned, and published. It also supports schema bindings, business-term schema relationships, schema introspection, and JSON Schema generation.
• L2 Object Model is the use-case layer. It pins one or more published data domains through domainRefs, declares named ObjectRole entries, selects relationship types, and applies narrow-only ObjectOverride entries. Resolution produces the effective object graph and its governed business terms.
• L3 Data Product is a role-scoped traversal subselection of exactly one published object model. Each selected entry is a { roleRef, path: [...] } pair. A path can cross a relationship, for example { roleRef: "employee", path: ["residentialAddress", "country"] }.
• L4 Channel renders one data product into an output. Supported channel types are FORM, PDF_DOCUMENT, VERIFIABLE_CREDENTIAL, API_PAYLOAD, and OID4VCI. Product-backed channels carry a DataProductRef; the current wire schema names that field setRef. A verifiable-credential channel adds credentialFormat, vct or doctype, optional namespace, claimMappings, and a version-pinned brandingRef. An OID4VCI channel composes one or more verifiable-credential channels and has no product binding of its own.

Each tier uses the DRAFT | PUBLISHED lifecycle. Snapshot versions make downstream references deterministic.

Semantic grounding and governance

BusinessTerm is an OCA capture-base definition: path is an array containing one segment at each tree node, valueType uses OCA tokens such as Text, Numeric, DateTime, Reference, and [Text], and children defines a compound Reference value. Meaning and governance are carried in the term's overlays, semanticTerms, and entryCodeScheme fields.

The R14 additive contract fields are also available on a business term. grounding records the source, an optional pinned legalBasis (sourceId and snapshotId), retrievedOn, and a GroundingKind of LEGAL_SOURCE, AUTHORITATIVE_REGISTER, STANDARD, or INTERNAL_DEFINITION. entryCodeScheme can carry the governed codeListKind values ENUMERATION, REFERENCE_LIST, and CODE_LIST. ObligationKind provides the governed OBLIGATION, REQUIREMENT, and CRITERION vocabulary where enterprise obligation records use it. These are additive fields; publish-time grounding enforcement is not part of this contract.

The governance overlays (classification, processing, residency, and assurance) are grounded in W3C DPV, GDPR, NIST FIPS 199, ISO 27001, and eIDAS2. They flow from the data-domain business term through object-model and data-product resolution into the channel output. A downstream tier may narrow a value, but never widen it.

Status and feature coverage

The current authoring API covers the full four-tier path:

Tier	Implemented capabilities
Data Domain	Create, update, delete, list, version, publish, resolve; manage Object Types, Business Terms, Relationship Types, schema bindings, schema relationships, external-schema proposals, and generated JSON Schema.
Object Model	Create, update, delete, list, version, publish, resolve; replace domain references, roles, relationship selections, and narrow-only overrides; generate JSON Schema.
Data Product	Create, update, delete, list, selection replacement, version, publish, and effective-contract resolution.
Channel	List, fetch, and delete any channel; author FORM, PDF_DOCUMENT, VERIFIABLE_CREDENTIAL, OID4VCI, and API_PAYLOAD channels; author credential branding.
Protocol integration	Derive credential designs from verifiable-credential channels, derive DCQL in preview or authored mode, and record ISSUE or REQUEST usage lineage for consumed traversals.

Enterprise license

The semantic-model authoring API declares the enterprise feature semantic-modeling.v1. Authoring writes, channel publication, credential-design derivation, authored DCQL, and schema registration require that feature. Reads, resolution, and pure JSON Schema generation are read operations; the OpenAPI descriptions identify them as not license-gated. A deployment with the feature enabled can use the complete EDK and VDX model.

This walkthrough covers the enterprise authoring path. The simple IDK configuration-based credential and DCQL paths remain separate and are documented in their protocol guides.

What the model drives

From the data domain, object model, data product, and channels, the platform derives:

• The wire form of the issued credential. The claim list and credential identity come from the verifiable-credential channel's claimMappings, not from a hand-typed design claim list.
• Selective-disclosure and governance policy. Business-term overlays and narrow-only downstream overrides flow into the effective data product and channel mapping.
• The verifier DCQL. The verifier query is derived from the same verifiable-credential channels used for issuance, so issuer and verifier agree on field identity.
• Usage lineage. Each derived credential design or authored DCQL query records the role, source object type, full traversal path, channel reference, artifact kind, and artifact version for every consumed business term.

What we will build

The walkthrough uses the layered authoring API rooted at /api/model/v1.

Step	Layer / surface	REST entry point	Page
L1: create the data-domain shell	Data Domain	POST /api/model/v1/data-domains	Data Domain
L1: add five object types	Object Types	POST /api/model/v1/data-domains/{dataDomainId}/object-types (x5)	Data Domain
L1: add two relationship types	Relationship Types	POST /api/model/v1/data-domains/{dataDomainId}/relationship-types (x2)	Data Domain
L1: publish and resolve	Data Domain lifecycle	PUT /api/model/v1/data-domains/{dataDomainId}/status then GET .../resolved	Data Domain
L2: create and curate the object model	Object Model	POST /api/model/v1/objects, then PUT /api/model/v1/objects/{objectModelId}/{domain-refs,roles,relationships,overrides}	Object Model
L2: publish and resolve	Object Model lifecycle	PUT /api/model/v1/objects/{objectModelId}/status then GET .../resolved	Object Model
L3: create and select the data product	Data Product	POST /api/model/v1/data-products, then PUT .../selection	Data Product
L3: publish and resolve	Data Product lifecycle	PUT /api/model/v1/data-products/{dataProductId}/status then GET .../resolved	Data Product
L4: two verifiable-credential channels	Channel	POST /api/model/v1/channels/credentials (x2)	Channels
L4: credential branding	Credential Branding	POST /api/model/v1/branding	Channels
L4: OID4VCI issuance channel	Channel	POST /api/model/v1/channels/oid4vci	Channels
Optional L4 outputs	Channel	POST /api/model/v1/channels/forms, /channels/pdf, or /channels/api	Channels
Derive issuer designs	Credential design	POST /api/v1/designs/credentials/fromdefinition	Issuing
Preview or author DCQL	Verifier DCQL	POST /api/dcql/v1/queries/preview or POST /api/dcql/v1/queries/authored	Verifying

All model and backend calls authenticate with an OIDC bearer token issued by the tenant's Authorization Server. The tenant is resolved from the token's tenant_id claim. Wallet-facing protocol endpoints are driven by the wallet and need no operator token.

Next steps

• Modeling Your World: the four tiers, business-term anatomy, governance, schema support, lineage, and license behavior
• Data Domain (L1): seed object types, business terms, and relationship types, then publish a stable version
• Object Model (L2): bind object types to use-case roles and apply narrow-only overrides
• Data Product (L3): select the exact traversals required by one issuance or verification scenario
• Channels (L4): render the data product as forms, documents, credentials, issuance, or API payloads
• Issuing: derive issuer designs from verifiable-credential channels and create the offer
• Verifying: derive a multi-credential DCQL query and verify a presentation
• Provenance & Operations: usage lineage, governance flow-through, versioning, and operational boundaries