Phase

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. Overview

This optional module defines journey-map grouping over intended Graph topology. A Phase is a high-level grouping, and a Step identifies one experienced CompositeState through compositeStateRef.

The module is intentionally first-level. It attaches directly to [UJG Graph] composition without requiring Surface, Runtime, Mapping, Observability, or Design System data. Surfaces describe how Graph subjects are presented. Runtime and Mapping describe what was actually observed.

Phase terms do not create Graph traversal, alter transition semantics, select child journey entries, or imply Runtime execution order. Runtime occurrence and phase-start derivation are defined by [UJG Mapping], not by this module.

Documents using this module compose the Graph context with https://ujg.specs.openuji.org/ed/ns/phase.context.jsonld.

2. Terminology

Phase: A high-level presentation grouping of Steps.
Step: A journey-map step that identifies exactly one experienced Graph CompositeState.

3. Phase

A Phase is a high-level grouping for Steps. order is display metadata; it does not determine Graph traversal, Mapping step order, or Runtime event order.

A Phase MUST be identified by an IRI.
A Phase MAY declare at most one integer order.
order MUST NOT be interpreted as Graph traversal, Mapping step order, Runtime event order, occurrence, or phase start.
A Phase groups the Steps whose phaseRef resolves to it; it does not list or own them.
A Phase MUST NOT directly reference journeys, composite states, states, or surfaces.

classDiagram
  class Phase {
    id
    order
  }

Example JSON node:

json

 {
  "@type": "Phase",
  "@id": "urn:ujg:phase:checkout",
  "order": 2
} 
 {
  "@type": "Phase",
  "@id": "urn:ujg:phase:checkout",
  "order": 2
} 

4. Step

A Step identifies one experienced CompositeState. The referenced composite state represents a distinct nested segment of the intended journey topology; its subjourneyId identifies the local child journey contained by that segment.

A Step MUST be identified by an IRI.
A Step MUST declare exactly one compositeStateRef.
compositeStateRef MUST reference a CompositeState defined in the Graph model.
A Step MAY declare at most one phaseRef referencing a Phase.
A Step MAY declare at most one integer order.
order MUST NOT be interpreted as Graph traversal, Mapping step order, Runtime event order, occurrence, or phase start.
compositeStateRef MUST NOT create traversal, alter transition semantics, select child journey entries, or imply Runtime execution order.
A Step MUST NOT use Surface resources as its semantic subject.

classDiagram
  class CompositeState
  class Phase
  class Step {
    id
    compositeStateRef
    phaseRef
    order
  }
  Step --> CompositeState : compositeStateRef
  Step --> Phase : phaseRef

Example JSON node:

json

 {
  "@type": "Step",
  "@id": "urn:ujg:step:enter-shipping",
  "compositeStateRef": "urn:ujg:state:shipping-segment",
  "phaseRef": "urn:ujg:phase:checkout",
  "order": 1
} 
 {
  "@type": "Step",
  "@id": "urn:ujg:step:enter-shipping",
  "compositeStateRef": "urn:ujg:state:shipping-segment",
  "phaseRef": "urn:ujg:phase:checkout",
  "order": 1
} 

5. Shared Semantics

compositeStateRef is the canonical assignment from a Step to Graph topology.
A Phase's associated topology is derived from the compositeStateRef values of the Steps that reference it with phaseRef.
Step and Phase terms do not repair missing Graph topology.
Consumers that do not implement this module MAY ignore Phase semantics while preserving recognized JSON-LD data during read-transform-write.

6. Normative Artifacts

6.1. Ontology

The Phase ontology is published at https://ujg.specs.openuji.org/ed/ns/phase.

turtle

 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgphase: <https://ujg.specs.openuji.org/ed/ns/phase#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix dct: <http://purl.org/dc/terms/> .

<https://ujg.specs.openuji.org/ed/ns/phase#> a owl:Ontology ;
  rdfs:label "UJG Phase Editor's Draft Vocabulary"@en ;
  dct:description "UJG Phase ontology declaration" .

### Classes

ujgphase:Phase a owl:Class ;
  rdfs:subClassOf ujg:Node .

ujgphase:Step a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgphase:compositeStateRef a owl:ObjectProperty ;
  rdfs:domain ujgphase:Step ;
  rdfs:range ujggraph:CompositeState .

ujgphase:phaseRef a owl:ObjectProperty ;
  rdfs:domain ujgphase:Step ;
  rdfs:range ujgphase:Phase .

ujgphase:order a owl:DatatypeProperty ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf (
      ujgphase:Step
      ujgphase:Phase
    )
  ] ;
  rdfs:range xsd:integer . 
 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgphase: <https://ujg.specs.openuji.org/ed/ns/phase#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix dct: <http://purl.org/dc/terms/> .

<https://ujg.specs.openuji.org/ed/ns/phase#> a owl:Ontology ;
  rdfs:label "UJG Phase Editor's Draft Vocabulary"@en ;
  dct:description "UJG Phase ontology declaration" .

### Classes

ujgphase:Phase a owl:Class ;
  rdfs:subClassOf ujg:Node .

ujgphase:Step a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgphase:compositeStateRef a owl:ObjectProperty ;
  rdfs:domain ujgphase:Step ;
  rdfs:range ujggraph:CompositeState .

ujgphase:phaseRef a owl:ObjectProperty ;
  rdfs:domain ujgphase:Step ;
  rdfs:range ujgphase:Phase .

ujgphase:order a owl:DatatypeProperty ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf (
      ujgphase:Step
      ujgphase:Phase
    )
  ] ;
  rdfs:range xsd:integer . 

6.2. JSON-LD Context

The Phase context is published at https://ujg.specs.openuji.org/ed/ns/phase.context.jsonld.

json-ld

 {
  "@context": {
    "@version": 1.1,

    "ujgphase": "https://ujg.specs.openuji.org/ed/ns/phase#",
    "phase": "https://ujg.specs.openuji.org/ed/ns/phase#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",

    "Phase": "ujgphase:Phase",
    "Step": "ujgphase:Step",

    "compositeStateRef": {
      "@id": "ujgphase:compositeStateRef",
      "@type": "@id"
    },
    "phaseRef": {
      "@id": "ujgphase:phaseRef",
      "@type": "@id"
    },
    "order": {
      "@id": "ujgphase:order",
      "@type": "xsd:integer"
    }
  }
} 
 {
  "@context": {
    "@version": 1.1,

    "ujgphase": "https://ujg.specs.openuji.org/ed/ns/phase#",
    "phase": "https://ujg.specs.openuji.org/ed/ns/phase#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",

    "Phase": "ujgphase:Phase",
    "Step": "ujgphase:Step",

    "compositeStateRef": {
      "@id": "ujgphase:compositeStateRef",
      "@type": "@id"
    },
    "phaseRef": {
      "@id": "ujgphase:phaseRef",
      "@type": "@id"
    },
    "order": {
      "@id": "ujgphase:order",
      "@type": "xsd:integer"
    }
  }
} 

6.3. Validation

The Phase SHACL shape is published at https://ujg.specs.openuji.org/ed/ns/phase.shape.

turtle

 @prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgphase: <https://ujg.specs.openuji.org/ed/ns/phase#> .
@prefix ujgphaseshape: <https://ujg.specs.openuji.org/ed/ns/phase.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ujgphaseshape:StepShape a sh:NodeShape ;
  sh:targetClass ujgphase:Step ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgphase:compositeStateRef ;
    sh:class ujggraph:CompositeState ;
    sh:nodeKind sh:IRI ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgphase:phaseRef ;
    sh:class ujgphase:Phase ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgphase:order ;
    sh:datatype xsd:integer ;
    sh:maxCount 1 ;
  ] .

ujgphaseshape:PhaseShape a sh:NodeShape ;
  sh:targetClass ujgphase:Phase ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgphase:order ;
    sh:datatype xsd:integer ;
    sh:maxCount 1 ;
  ] . 
 @prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgphase: <https://ujg.specs.openuji.org/ed/ns/phase#> .
@prefix ujgphaseshape: <https://ujg.specs.openuji.org/ed/ns/phase.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ujgphaseshape:StepShape a sh:NodeShape ;
  sh:targetClass ujgphase:Step ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgphase:compositeStateRef ;
    sh:class ujggraph:CompositeState ;
    sh:nodeKind sh:IRI ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgphase:phaseRef ;
    sh:class ujgphase:Phase ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgphase:order ;
    sh:datatype xsd:integer ;
    sh:maxCount 1 ;
  ] .

ujgphaseshape:PhaseShape a sh:NodeShape ;
  sh:targetClass ujgphase:Phase ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgphase:order ;
    sh:datatype xsd:integer ;
    sh:maxCount 1 ;
  ] . 

7. Examples

7.1. Graph Segment With Phase Grouping

json

 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/phase.context.jsonld"
  ],
  "@id": "https://example.com/ujg/phase/checkout.jsonld",
  "@type": "UJGDocument",
  "nodes": [
    {
      "@type": "Journey",
      "@id": "urn:ujg:journey:checkout-page",
      "defaultEntryRef": "urn:ujg:entry:checkout-page-default",
      "entryRefs": ["urn:ujg:entry:checkout-page-default"],
      "stateRefs": ["urn:ujg:state:shipping-segment"]
    },
    {
      "@type": "JourneyEntry",
      "@id": "urn:ujg:entry:checkout-page-default",
      "stateRef": "urn:ujg:state:shipping-segment"
    },
    {
      "@type": "CompositeState",
      "@id": "urn:ujg:state:shipping-segment",
      "label": "Shipping segment",
      "subjourneyId": "urn:ujg:journey:shipping-segment"
    },
    {
      "@type": "Journey",
      "@id": "urn:ujg:journey:shipping-segment",
      "defaultEntryRef": "urn:ujg:entry:shipping-default",
      "entryRefs": ["urn:ujg:entry:shipping-default"],
      "stateRefs": ["urn:ujg:state:shipping-form"]
    },
    {
      "@type": "JourneyEntry",
      "@id": "urn:ujg:entry:shipping-default",
      "stateRef": "urn:ujg:state:shipping-form"
    },
    {
      "@type": "State",
      "@id": "urn:ujg:state:shipping-form",
      "label": "Shipping form"
    },
    {
      "@type": "Phase",
      "@id": "urn:ujg:phase:checkout",
      "order": 2
    },
    {
      "@type": "Step",
      "@id": "urn:ujg:step:enter-shipping",
      "compositeStateRef": "urn:ujg:state:shipping-segment",
      "phaseRef": "urn:ujg:phase:checkout",
      "order": 1
    }
  ]
} 
 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/phase.context.jsonld"
  ],
  "@id": "https://example.com/ujg/phase/checkout.jsonld",
  "@type": "UJGDocument",
  "nodes": [
    {
      "@type": "Journey",
      "@id": "urn:ujg:journey:checkout-page",
      "defaultEntryRef": "urn:ujg:entry:checkout-page-default",
      "entryRefs": ["urn:ujg:entry:checkout-page-default"],
      "stateRefs": ["urn:ujg:state:shipping-segment"]
    },
    {
      "@type": "JourneyEntry",
      "@id": "urn:ujg:entry:checkout-page-default",
      "stateRef": "urn:ujg:state:shipping-segment"
    },
    {
      "@type": "CompositeState",
      "@id": "urn:ujg:state:shipping-segment",
      "label": "Shipping segment",
      "subjourneyId": "urn:ujg:journey:shipping-segment"
    },
    {
      "@type": "Journey",
      "@id": "urn:ujg:journey:shipping-segment",
      "defaultEntryRef": "urn:ujg:entry:shipping-default",
      "entryRefs": ["urn:ujg:entry:shipping-default"],
      "stateRefs": ["urn:ujg:state:shipping-form"]
    },
    {
      "@type": "JourneyEntry",
      "@id": "urn:ujg:entry:shipping-default",
      "stateRef": "urn:ujg:state:shipping-form"
    },
    {
      "@type": "State",
      "@id": "urn:ujg:state:shipping-form",
      "label": "Shipping form"
    },
    {
      "@type": "Phase",
      "@id": "urn:ujg:phase:checkout",
      "order": 2
    },
    {
      "@type": "Step",
      "@id": "urn:ujg:step:enter-shipping",
      "compositeStateRef": "urn:ujg:state:shipping-segment",
      "phaseRef": "urn:ujg:phase:checkout",
      "order": 1
    }
  ]
} 