UJG / Editor's Draft /
W3C Community Group Draft Report

Domain Model

draft

Status of this Document

This report was published by the User Journal Graph Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .

Last Update
2026-08-24
Editors
  • Seva Dolgopolov
Group
User Journal Graph Community Group
Repository
View Source
License
W3C-Software-and-Document

1. Overview

The Domain Model Document Extension defines an optional, technology-neutral application domain model attached to a UJGDocument.

The extension is a Document Extension, not an RDF optional module. Its payload is opaque JSON from the perspective of generic UJG JSON-LD processing. It is validated by JSON Schema and derives traceability from [UJG Domain Requirements].

The Domain Model Extension does not prescribe technical realization.

2. Extension Attachment

The extension value is attached to UJGDocument.extensions using the key org.openuji.domain-model.

The value of extensions["org.openuji.domain-model"] MUST be a DomainModel payload conforming to this specification.

Core MUST NOT define Domain Model-specific properties such as domainModel or domainModelRef.

3. Processing Model

Generic UJG processors treat the Domain Model payload as opaque JSON.

A processor that does not implement this extension MAY ignore its semantics while preserving its JSON payload during non-lossy read-transform-write.

A processor implementing this extension MUST validate the payload using the Domain Model JSON Schema.

A Domain Model-aware validator MUST resolve referenced Domain Requirements, resolve internal Domain Model references, and apply the semantic rules defined by this specification.

Unknown Domain Model semantics MUST NOT affect Core identity, import resolution, reference resolution, Graph traversal, or Graph semantics.

4. Relationship to Domain Requirements

Domain Model traceability flows through Domain Requirements.

flowchart TD
  element[DomainModel element] -->|domainRequirementRefs| requirement[DomainRequirement]
  requirement -->|source-specific requirement reference| semantics[UJG semantics]

The Domain Model Extension MUST NOT duplicate direct references to Conditions, Effects, States, EntryBindings, or other UJG semantic sources for requirement traceability.

Domain Requirements are the boundary between UJG journey semantics and the Domain Model.

5. Domain Model Vocabulary

Version 0.1 defines exactly these payload object types:

  • DomainModel

  • Entity

  • ValueObject

  • Property

  • Association

  • DomainOperation

  • Invariant

classDiagram
  class DomainModel {
    formatVersion
    id
    domainRequirementRefs
    entities
    valueObjects
    associations
    domainOperations
    invariants
  }
  class Entity {
    id
    label
    description
    domainRequirementRefs
    properties
  }
  class ValueObject {
    id
    label
    description
    domainRequirementRefs
    properties
  }
  class Property {
    id
    label
    description
    domainRequirementRefs
    valueType
    allowedValues
  }
  class Association {
    sourceRef
    targetRef
  }
  class DomainOperation {
    actsOnRefs
    preconditions
    postconditions
  }
  class Invariant {
    appliesToRefs
    assertion
  }
  DomainModel --> "0..*" Entity : entities
  DomainModel --> "0..*" ValueObject : valueObjects
  DomainModel --> "0..*" Association : associations
  DomainModel --> "0..*" DomainOperation : domainOperations
  DomainModel --> "0..*" Invariant : invariants
  Entity --> "0..*" Property : properties
  ValueObject --> "0..*" Property : properties

Version 0.1 does not define aggregate boundaries, domain services, domain events, repositories, commands, bounded contexts, persistence models, API models, executable rule languages, or technical architecture.

5.1. DomainModel

A DomainModel is the root payload stored in extensions["org.openuji.domain-model"].

PropertyRequirement
formatVersionMUST be "0.1".
idMUST be a stable identifier for the Domain Model.
domainRequirementRefsMUST declare the complete set of UJG Domain Requirements this Domain Model claims to satisfy.
entitiesMUST exist; MAY be empty.
valueObjectsMUST exist; MAY be empty.
associationsMUST exist; MAY be empty.
domainOperationsMUST exist; MAY be empty.
invariantsMUST exist; MAY be empty.

Every requirement listed in DomainModel.domainRequirementRefs MUST be referenced by at least one contained Domain Model element.

Every domainRequirementRefs value on a contained element MUST also occur in the root DomainModel.domainRequirementRefs.

5.2. Common Domain Element

Every Entity, ValueObject, Property, Association, DomainOperation, and Invariant shares the same basic identification and traceability properties.

PropertyRequirement
idMUST uniquely identify the element within the Domain Model and remain stable while the element's semantics remain stable.
labelMUST provide a concise human-readable domain name.
descriptionMAY provide explanatory human-readable text.
domainRequirementRefsMUST contain at least one reference, contain no duplicates, and contain only references declared by the containing DomainModel.

5.3. Entity and ValueObject

An Entity represents a domain object for which independent identity matters. A ValueObject represents a domain value whose meaning is determined by its value rather than an independent identity lifecycle.

Both object types use the Common Domain Element properties and add:

PropertyRequirement
propertiesMUST be an array of Property.

The specification does not prescribe how entity instances are identified or persisted. A producer SHOULD NOT introduce a ValueObject merely to wrap a primitive value without domain significance.

5.4. Property

A Property describes domain information belonging to an Entity or ValueObject.

In addition to the Common Domain Element properties, a Property has:

PropertyRequirement
valueTypeMUST be one of string, integer, number, boolean, date, or datetime.
allowedValuesMAY restrict the property to a finite set of values.

The specification does not define storage types, programming-language types, columns, nullability, or serialization formats.

5.5. Association

An Association represents a required relationship between domain objects.

In addition to the Common Domain Element properties, an Association has:

PropertyRequirement
sourceRefMUST resolve to an Entity or ValueObject in the same Domain Model.
targetRefMUST resolve to an Entity or ValueObject in the same Domain Model.

Version 0.1 does not standardize cardinality and does not define ORM or persistence relationships.

5.6. DomainOperation

A DomainOperation represents behavior required from the domain.

In addition to the Common Domain Element properties, a DomainOperation has:

PropertyRequirement
actsOnRefsMUST be an array of references to Entity or ValueObject elements in the same Domain Model.
preconditionsMUST be an array of technology-neutral semantic statements.
postconditionsMUST be an array of technology-neutral semantic statements.

Version 0.1 deliberately defines no predicate or expression language. A DomainOperation does not imply an API operation, HTTP endpoint, service method, UI action handler, or execution location.

5.7. Invariant

An Invariant represents a domain rule that must remain true across valid domain behavior.

In addition to the Common Domain Element properties, an Invariant has:

PropertyRequirement
appliesToRefsMUST reference Domain Model elements.
assertionMUST be a technology-neutral semantic statement.

Version 0.1 defines no executable invariant language.

6. Validation Semantics

JSON Schema is responsible only for structural validation. Cross-reference resolution MUST be performed by a Domain Model-aware UJG validator.

6.1. Internal References

All Domain Model element IDs MUST be unique.

Association.sourceRef, Association.targetRef, DomainOperation.actsOnRefs, and Invariant.appliesToRefs MUST resolve within the same Domain Model.

A structurally valid JSON document containing dangling internal references is semantically invalid.

6.2. Domain Requirement Resolution

Every value in domainRequirementRefs MUST resolve to a UJG Domain Requirement available through the containing UJG document and its normal import resolution.

A dangling Domain Requirement reference makes the Domain Model invalid.

6.3. Requirement Coverage

For every Domain Requirement declared by DomainModel.domainRequirementRefs, at least one contained Domain Model element MUST reference that requirement.

This permits one requirement to justify multiple Domain Model elements, and one Domain Model element to satisfy multiple requirements. No one-to-one mapping is implied.

7. Realization Boundary

The Domain Model describes domain semantics.

It MUST NOT prescribe frontend versus backend placement, browser versus server execution, local or remote persistence, SQL or NoSQL, APIs or transport, framework architecture, repositories or controllers, authentication mechanisms, messaging infrastructure, or deployment topology.

8. Normative Artifacts

The normative Domain Model JSON Schema is defined below and is published at https://ujg.specs.openuji.org/ed/extensions/domain-model/domain-model.schema.json.

For namespace-style artifact discovery, the same schema is also published at https://ujg.specs.openuji.org/ed/ns/domain-model.schema.json.

9. Examples

9.1. Workshop Waitlist Domain Model

This example attaches a Domain Model payload to a UJGDocument. The example assumes the referenced Domain Requirement nodes are present in the containing document or resolvable through normal UJG imports.