Architecture

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-07-15
Editors: Seva Dolgopolov
Group: User Journal Graph Community Group
Repository: View Source
License: W3C-Software-and-Document

1. Abstract

The User Journey Graph (UJG) standardizes user experience as computable data. It decouples the Definition of Intent (Design) from the Observation of Reality (Telemetry). This separation creates a single source of truth for Designers, Developers, and Analysts. As a deterministic protocol, it supports automation by AI agents across these roles, ensuring structural consistency.

2. Conceptual Stack

The main spec family is organized into five logical layers:

The Core (Transport): The universal JSON-LD envelope. Ensures any tool—human or AI—can parse the file structure without ambiguity.
The Graph (Definition): Defines the "Happy Path." It is the vocabulary for States, Transitions, and Composition (sub-journey referencing).
The Surface (Materialization): Exposes supported Graph nodes as addressable human-facing surfaces, touchpoints scoped to CompositeState boundaries, human users, and visible occurrences.
The Runtime (Execution): Captures the "Actual Path." It records observed surface events as a causal chain.
The Mapping (Conformance): Closes the loop. It resolves Reality(Runtime) through Surface onto Intent(Graph) to calculate conversion and detect friction.

3. Guiding Principles

Graph First: User experience is an automata, not a list of URLs.
Stable Identity: Entities must be named with URIs to survive refactors.
Separation of Concerns: A "Journey" (the plan) is immutable; observed surface events are runtime facts.
Vendor Neutrality: The spec defines data shapes, not visualization rules.

4. Optional Modules

The Editor's Draft also publishes a parallel family of optional modules for capabilities that build on the core UJG layers without expanding the shared interoperability baseline. Earlier drafts called these "supported extensions", but the normative model is now module-oriented: optional capabilities that need interoperable graph terms publish their own ontology, JSON-LD context, and SHACL shape.

Optional modules are where new ideas can live before every UJG document needs them. They can add meaning on top of the main spec family, but they should leave the older layers intact. When an idea becomes common enough that most compliant tools need it, it belongs in the main spec family instead of staying optional.

Optional modules can grow in steps. A small module can first give the shared UJG layers a simple thing to point at. Later modules can build on that thing and describe it in more detail. This lets new capabilities become precise without forcing the shared baseline, or this architecture page, to know every specialized vocabulary that may be added later.

First-level optional modules are small bridges that attach directly to main spec concepts. Second-level optional modules compose one or more shared layers or first-level bridges.

5. Opaque Extensions

The specification distinguishes published module vocabularies from opaque deployment-private payloads. Opaque payloads are useful for local metadata and vendor integration, but they are not a substitute for terms that need interoperable semantics. Processing rules for opaque payloads and published module terms are defined by the modules that own those mechanisms.