Modeling Your World

The overview introduced the four tiers: Data Domain, Object Model, Data Product, and Channel. This page explains how they describe an organization's world, how governance flows through each tier, how schemas are grounded, and how concrete wire forms are derived. The model is the authoritative source; issuer designs and verifier DCQL are derived from it.

Modeling your world

Before any credential is designed, a Data Domain lets an organization describe the kinds of party it deals with, the business terms those parties carry, and the relationships between them. Everything downstream derives from this governed layer.

A Data Domain is bound to a Party. Every data domain is owned through ownerPartyRef. The response schema also includes the tenant, lifecycle status, monotonic version, root overlays, and timestamps. A data domain is the governed source for its object types, business terms, relationship types, and schema bindings.

Object Types are party types. An ObjectType with kind: "PREDEFINED" names a platform party type through partyType, such as natural_person, organization, or address. A SPECIALIZATION extends another object type through specializes: { entity: "Person" } and adds business terms without declaring another partyType. Both kinds are parties. Non-party structured values are anonymous inline Reference business terms with children.

Business Terms are the capture-base tree. A BusinessTerm has a single-segment path, an OCA valueType, and optional children for a compound Reference. Nested paths are composed from the ancestor chain. The Data Domain wire schema exposes object types in its entities array and relationship types in its relationships array; these are the current response property names.

Relationship Types connect parties. A RelationshipType has a name used as a traversal segment, a relationType token, source and target RelationshipEnd values, per-end cardinality, optional roles, and its own overlay bag. A relationship type is the right place to connect two parties. Inline compounds are for structured data owned by one object type.

The four tiers

The model is structured into four versioned tiers:

1. Data Domain (L1) defines Object Types, Business Terms, Relationship Types, governance, and schema bindings.
2. Object Model (L2) pins one or more published data domains through domainRefs, binds use-case roles to object types, selects relationship types, and applies narrow-only ObjectOverride entries.
3. Data Product (L3) pins one published object model through objectModelRef and selects the exact (roleRef, path) traversals needed by one scenario.
4. Channel (L4) pins one data product through the current wire field setRef (DataProductRef) and renders its selections as a form, PDF/document, verifiable credential, OID4VCI issuance definition, or API payload. Credential branding is a reusable L4 presentation overlay.

Each tier uses DRAFT | PUBLISHED. Published snapshots are immutable inputs to downstream references.

Business-term anatomy

The Data Domain BusinessTerm schema uses these fields:

Field	Meaning
path	One path segment as an array, for example ["given_name"]. A segment never contains ..
valueType	An OCA capture-base token: Text, Numeric, Boolean, Binary, DateTime, Reference, or an array form such as [Text] or [Reference].
overlays	The typed overlay bag for cardinality, conformance, format, entry codes, unit, standard, character encoding, sensitivity, widget hint, selective disclosure, localized text, and governance.
children	Child business terms for a Reference compound. Scalar terms have no children.
entityType	Optional PERSON or ORGANIZATION marker for a compound that is party-typed.
entryCodeScheme	Optional SkosConceptSchemeReference with schemeUri, schemeName, and the governed codeListKind.
semanticTerms	Optional SemanticTermReference entries with semanticVocabularyId, termUri, and an optional termLabel. This is the RDF and vocabulary linkage point.
schemaRelationships	Object-type-level relationships to external schema attributes, each anchored at a canonical semanticPath.
grounding	R14 source provenance: source, optional pinned legalBasis, retrievedOn, and kind.

Governance overlays

The four governance overlays on a business term are authored once in overlays and flow through every tier. They are grounded in W3C DPV, GDPR, NIST FIPS 199, ISO 27001, and eIDAS2.

• classification carries the ISO 27001 label, NIST FIPS 199 confidentiality/integrity/availability impact, pii, and the GDPR special-category marker.
• processing carries DPV purposes and operations. Each purpose can carry a GDPR Article 6 legalBasis, Article 9 condition, necessity signal, and retention rule.
• residency carries allowed and denied regions, localization requirements, and the Chapter V transfer mechanism.
• assurance carries the eIDAS level of assurance, attestation type, and authentic-source reference.

The data-domain root overlays additionally supports localized meta, jurisdiction governance, a controller, a classification scheme, NIS2, MiCA, and forward-compatible extensions.

R14 grounding

R14 adds fields without changing the draft/published lifecycle. A term can record:

{
  "grounding": {
    "source": "https://example.test/legal-source/hrw/article-18",
    "legalBasis": {
      "sourceId": "nl-hrw",
      "snapshotId": "nl-hrw-2026-01-01"
    },
    "retrievedOn": "2026-01-15T09:30:00Z",
    "kind": "LEGAL_SOURCE"
  },
  "entryCodeScheme": {
    "schemeUri": "https://example.test/vocab/country",
    "schemeName": "Country codes",
    "codeListKind": "REFERENCE_LIST"
  }
}

The supported GroundingKind values are LEGAL_SOURCE, AUTHORITATIVE_REGISTER, STANDARD, and INTERNAL_DEFINITION. codeListKind accepts ENUMERATION, REFERENCE_LIST, and CODE_LIST. The ObligationKind vocabulary is OBLIGATION, REQUIREMENT, and CRITERION where obligation records use it. R14 is field-level contract support; publish-time enforcement of grounding is not included.

Schemas and external grounding

A Data Domain can bind named external or internal schemas through /data-domains/{dataDomainId}/schema-bindings. A binding records a SchemaRef, purpose, and origin. Schema relationships are attached to an Object Type and relate a canonical business-term semanticPath to an external attribute path through SemanticAttributeSchemaRelationship.

The supported relationship values include DERIVED_FROM_EXTERNAL, USES_EXTERNAL_SHAPE, EQUIVALENT_TO_EXTERNAL, NEAR_EQUIVALENT_TO_EXTERNAL, and EXPORTS_AS_EXTERNAL. A relationship can also carry direction, equivalence, confidence, notes, and an optional transform. The API can introspect a binding, propose relationships, persist reviewed relationships, and generate a data-domain JSON Schema. JSON_SCHEMA is the currently supported generated schema target; XML_SCHEMA, SD_JWT_VCT, JSON_LD_CONTEXT, and OCA_BUNDLE remain schema-type vocabulary values, but generation currently rejects unsupported targets.

The Object Model can generate a conformance-bearing JSON Schema from its resolved graph. Required business terms populate the enclosing object's required array, object-type boundaries nest, entry-code narrowing maps to enum, and repeating terms map to arrays. Pure generation is a read; setting register: true additionally registers the generated schema and is license-gated.

How wire forms are derived

Wire forms are derivations from a published Data Product and Channel, not a separate semantic authoring tier.

Verifiable-credential channel = a Data Product reference plus output mappings. ChannelFieldMapping uses fieldName and a set object containing the selected { roleRef, path }. VcClaimMapping uses the same set selection and can add a flat claimPath, an mdoc namespace, and a disclosure mode of ALWAYS or SELECTIVE. The channel carries credentialFormat, optional vct and vctHostingMode for SD-JWT VC, or doctype and namespace for mdoc, plus optional jsonLdContexts and brandingRef.

Other channels use the same data-product binding contract. Forms add fields and stepLabels; PDF/document channels add templateRef, placements, and repeatedSections; API-payload channels add payloadName, role, namingConvention, and externalPathMappings. The OID4VCI channel composes one or more VC channels through credentialConfigurations, each with a credentialConfigurationId, channelRef, signing, and offer settings.

Issuer credential design is created at POST /api/v1/designs/credentials/fromdefinition with a version-pinned channelRef. The claim list, selective-disclosure posture, ordering, credential format, and credential-type identity come from the VC channel. Issuance-only overlays remain on the design request. Each consumed traversal records an ISSUE usage row.

Verifier DCQL is derived at POST /api/dcql/v1/queries/preview or POST /api/dcql/v1/queries/authored. Preview returns the derived query without persistence or lineage; authored persists the query and records REQUEST usage rows. Multiple VC channels produce a multi-credential DCQL query.

For example, the Data Product selection { roleRef: "employee", path: ["residentialAddress", "country"] } can map to the VC claimPath: ["address", "country"]. The path segments remain clean arrays; an mdoc namespace is carried in namespace, never as a claim-path segment.

Narrowing and version pinning

Resolution applies these layers in order. Every downstream override is narrow-only:

1. Data Domain BusinessTerm (L1) is canonical: valueType, children, entryCodeScheme, semanticTerms, grounding, and overlays.
2. Object Model (L2) applies ObjectOverride entries keyed by (roleRef, path). The allow-list includes conformance, sdPolicy, cardinality, entryCodesSubset, sensitive, and retention.
3. Data Product (L3) applies ProductOverride entries keyed by (roleRef, path). It can tighten conformance, cardinality, entryCodesSubset, and sensitive.
4. Channel (L4) selects and maps existing data-product entries. A channel can choose a wire claimPath, disclosure mode, field rendering, document placement, or API path; it does not loosen the resolved data contract.
5. Credential design overlays are issuance-only presentation and hosting values derived after the channel.

The version pins make derivation deterministic:

• Object Model domainRefs pins each Data Domain id and version.
• Data Product objectModelRef pins one Object Model id and version.
• Product-backed Channel setRef carries a DataProductRef with dataProductId and dataProductVersion.
• An OID4VCI channel pins each VC channel through channelRef and channelVersion.
• Credential branding is pinned through brandingRef and its version.

Changing a draft creates a new snapshot; an already-published downstream reference continues to resolve against the pinned version.

Usage lineage

Derived protocol artifacts record one semantic-usage row for every consumed traversal. A row carries:

Column	Meaning
role_ref	The Object Model role that contributed the traversal, such as employee or employer.
source_entity	The Object Type that declares the selected Business Term, such as Person or Employee.
traversal_path	The complete path consumed from the Data Product, such as ["residentialAddress","country"].
role	ISSUE for credential-design derivation or REQUEST for authored DCQL.
artifact_kind	The derived artifact kind, such as CREDENTIAL_DESIGN or DCQL_QUERY.
artifact_id, artifact_version	The artifact and the version captured at derivation.
channel_id, channel_version	The VC Channel that supplied the mapping.

The lineage read surface can find usage by path, artifact, or Channel. Preview operations deliberately do not persist a query or write lineage. The lineage row preserves the role, source Object Type, traversal path, and Channel identity needed to answer which credentials issue or request a term.

Enterprise license

The semantic-model API declares the enterprise feature semantic-modeling.v1 in OpenAPI. Authoring writes and schema registration require that feature. Resolution, read operations, and pure schema generation do not require an entitlement according to their operation descriptions.

The feature is checked at the command boundary, so the REST operation metadata and runtime checks use the same key. A deployment without the feature receives FORBIDDEN for gated writes; a deployment with semantic-modeling.v1 can author all four tiers and the protocol derivations.

Pagination

Every list endpoint in /api/model/v1 uses the common page envelope. The main list families are /data-domains, /objects, /data-products, /channels, and /branding. Object Type and Relationship Type sub-collections also return paged summaries.

Parameter	Meaning
limit	Page size, clamped to [1, 100], default 20.
offset	Number of items to skip.
page	Zero-based page index, usable instead of offset.
size	Page-size alias for limit.
sort	Resource-specific sortable field, normally createdAt.
sortDirection	ASC or DESC, normally DESC.
resource filters	nameContains, status, objectModelId, dataProductId, or channel where the endpoint supports them.

Every list response has this shape:

{
  "data": [ /* page of resources, never a bare top-level array */ ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "page": 0,
    "size": 20,
    "total": 7,
    "totalPages": 1,
    "hasMore": false
  }
}

The channel list returns data as ChannelEnvelope entries. Read the discriminator from .data[].channel and the concrete definition from .data[].payload.

Next steps

• Data Domain (L1): define object types, business terms, relationship types, and schema bindings
• Object Model (L2): bind object types to roles, select relationships, and apply narrow-only overrides
• Data Product (L3): select the exact business-term traversals for one scenario
• Channels (L4): render a data product as a form, document, credential, issuance definition, or API payload
• Provenance & Operations: inspect usage lineage and operational boundaries