Graph

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 .

Editors: Seva Dolgopolov
Group: User Journal Graph Community Group
Repository: View Source
License: W3C-Software-and-Document

1. Overview

This module defines the vocabulary for intended user flow. It extends [UJG Core] to support structured, interactive graphs with composition via sub-journey references, organization tags, and reusable outgoing navigation patterns.

2. Terminology

Journey: A named container for a user flow.
State: A discrete node in the experience (e.g., a screen, modal).
Transition: A directed edge between two states.
CompositeState: A state that encapsulates another Journey (sub-journey).
OutgoingTransition: A one way edge pointing to a next possible State
OutgoingTransitionGroup: A reusable set of outgoing transitions that a Consumer can treat as present on multiple states (e.g., global nav).

3. The Core Graph

A Journey MUST consist of States connected by Transitions.

3.1. Visual Model

graph LR
    A[State: Product] -->|Transition: Add| B[State: Cart]

3.2. Data Model

3.2.1. The Journey Container

A Journey MUST include:

type: "Journey"
id: Unique URI/URN.
startState: ID of the entry State or CompositeState.
stateRefs: Array of IDs of State or CompositeState Nodes.
transitionRefs: Array of IDs of Transition Nodes.
outgoingTransitionGroupRefs: (Optional) Array of IDs of OutgoingTransitionGroup Nodes.

3.2.2. The State Object

A State MUST include:

type: "State"
id: Unique URI/URN.
label: Human-readable string.
tags: (Optional) Array of strings for grouping (e.g., ["phase:checkout"]).

3.2.3. The Transition Object

A Transition MUST include:

type: "Transition"
id: Unique URI/URN.
from: ID of the source State or CompositeState.
to: ID of the target State or CompositeState.
label: (Optional) Action name.

4. Composition (CompositeState)

Composition allows a node to reference an entire sub-journey, enabling "zoomable" graph interactions.

4.1. Visual Model

graph LR
    H[Home] --> C
    subgraph C [Composite State: Checkout]
      direction LR
      s1[Shipping] --> s2[Payment]
    end
    C --> E[Exit]

4.2. Schema

A CompositeState MUST include:

type: "CompositeState"
id: Unique URI/URN.
label: Human-readable string.
subjourneyId: The ID of the target Journey.

5. Reusability (OutgoingTransitionGroup)

An OutgoingTransitionGroup defines reusable outgoing transitions (e.g., headers/footers) to avoid duplicating common navigation across many states.

An OutgoingTransitionGroup MUST include:

type: "OutgoingTransitionGroup"
id: Unique URI/URN.
outgoingTransitionRefs: Array of IDs of OutgoingTransition Nodes.

An OutgoingTransition MUST include:

type: "OutgoingTransition"
id: Unique URI/URN.
to: Target State or CompositeState ID.
label: (Optional) Action name.

5.1. Visual Model

graph TD
    %% Global Destinations defined in the Group
    subgraph Global [Global Navigation]
      direction LR
      H[Target: Home]
      P[Target: Profile]
    end

    %% The Standard User Journey
    subgraph Flow [Checkout User Journey]
      direction LR
      S1[State: Shipping] -->|Explicit| S2[State: Payment]
    end

    %% The Injection Logic (Applies to ALL states in Flow)
    S1 -.->|Outgoing| H
    S1 -.->|Outgoing| P
    S2 -.->|Outgoing| H
    S2 -.->|Outgoing| P
    
    %% Styling for clarity
    linkStyle 1,2,3,4 stroke-dasharray: 5 5, stroke:green, color:green;

5.2. Processing Model (Injection)

When a Consumer loads a Journey referencing outgoingTransitionGroupRefs:

Resolution::

The Consumer MUST resolve each referenced OutgoingTransitionGroup
The Consumer MUST resolve each outgoingTransitionRefs entry to an OutgoingTransition.

Iteration: The Consumer MUST iterate over every State and CompositeState ID in stateRefs.
Injection: The Consumer MUST treat each iterated state as having an outgoing edge to every resolved OutgoingTransition to.
Deduplication: A Consumer SHOULD treat injected and explicit edges with the same effective from and to as one effective edge.

6. Validation Rules

To ensure graph integrity, the following constraints MUST be met:

Reference Integrity: All startState, stateRefs, transitionRefs, outgoingTransitionGroupRefs, outgoingTransitionRefs, from, and to IDs MUST resolve to valid Nodes within the current scope or imported modules.
Composition Safety: subjourneyId MUST resolve to a valid Journey.
Group Resolution: Every ID in outgoingTransitionGroupRefs MUST resolve to an OutgoingTransitionGroup.
Outgoing Resolution: Every ID in outgoingTransitionRefs MUST resolve to an OutgoingTransition.

Appendix: Combined JSON Example

json

 {
  "@context": "https://ujg.specs.openuji.org/ed/context.jsonld",
  "type": "UJGDocument",
  "specVersion": "1.0",
  "items": [
    {
      "type": "Journey",
      "id": "urn:ujg:journey:main-site",
      "startState": "urn:ujg:state:home",
      "stateRefs": ["urn:ujg:state:home", "urn:ujg:state:checkout-flow"],
      "transitionRefs": ["urn:ujg:transition:home-to-checkout"],
      "outgoingTransitionGroupRefs": ["urn:ujg:otg:global-header"]
    },

    {
      "type": "Transition",
      "id": "urn:ujg:transition:home-to-checkout",
      "from": "urn:ujg:state:home",
      "to": { "id": "urn:ujg:state:checkout-flow", "type": "CompositeState" },
      "label": "Buy Now"
    },

    { "type": "State", "id": "urn:ujg:state:home", "label": "Home Page", "tags": ["phase:landing"] },

    {
      "type": "CompositeState",
      "id": "urn:ujg:state:checkout-flow",
      "label": "Checkout Process",
      "subjourneyId": "urn:ujg:journey:checkout"
    },

    { "type": "State", "id": "urn:ujg:state:profile", "label": "Profile" },

    {
      "type": "OutgoingTransition",
      "id": "urn:ujg:ot:go-home",
      "to": "urn:ujg:state:home",
      "label": "Home"
    },

    {
      "type": "OutgoingTransition",
      "id": "urn:ujg:ot:go-profile",
      "to": "urn:ujg:state:profile",
      "label": "Profile"
    },

    {
      "type": "OutgoingTransitionGroup",
      "id": "urn:ujg:otg:global-header",
      "outgoingTransitionRefs": ["urn:ujg:ot:go-home", "urn:ujg:ot:go-profile"]
    }
    
  ]
} 
 {
  "@context": "https://ujg.specs.openuji.org/ed/context.jsonld",
  "type": "UJGDocument",
  "specVersion": "1.0",
  "items": [
    {
      "type": "Journey",
      "id": "urn:ujg:journey:main-site",
      "startState": "urn:ujg:state:home",
      "stateRefs": ["urn:ujg:state:home", "urn:ujg:state:checkout-flow"],
      "transitionRefs": ["urn:ujg:transition:home-to-checkout"],
      "outgoingTransitionGroupRefs": ["urn:ujg:otg:global-header"]
    },

    {
      "type": "Transition",
      "id": "urn:ujg:transition:home-to-checkout",
      "from": "urn:ujg:state:home",
      "to": { "id": "urn:ujg:state:checkout-flow", "type": "CompositeState" },
      "label": "Buy Now"
    },

    { "type": "State", "id": "urn:ujg:state:home", "label": "Home Page", "tags": ["phase:landing"] },

    {
      "type": "CompositeState",
      "id": "urn:ujg:state:checkout-flow",
      "label": "Checkout Process",
      "subjourneyId": "urn:ujg:journey:checkout"
    },

    { "type": "State", "id": "urn:ujg:state:profile", "label": "Profile" },

    {
      "type": "OutgoingTransition",
      "id": "urn:ujg:ot:go-home",
      "to": "urn:ujg:state:home",
      "label": "Home"
    },

    {
      "type": "OutgoingTransition",
      "id": "urn:ujg:ot:go-profile",
      "to": "urn:ujg:state:profile",
      "label": "Profile"
    },

    {
      "type": "OutgoingTransitionGroup",
      "id": "urn:ujg:otg:global-header",
      "outgoingTransitionRefs": ["urn:ujg:ot:go-home", "urn:ujg:ot:go-profile"]
    }
    
  ]
} 

References

Informative References

[UJG Core]: UJG Core. /ed/core