Core

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 .

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

1. Overview

This specification defines a mandatory envelope for all User Journey Graph (UJG) files. It establishes a uniform wire protocol allowing any consumer to parse headers and enumerate contained objects, independent of the specific module types (e.g., Journey, State, Transition) contained within.

2. General Requirements

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119] and [RFC8174].

2.1. File Format

Encoding: Data MUST be valid [JSON] encoded in UTF-8.
Compliance: Data MUST be valid [JSON-LD 1.1.].

2.2. Document Structure

Root Object: The root of the file MUST be a valid single UJGDocument bundle.
Context: The root MUST include a @context object defining:
- id aliased to @id
- type aliased to @type
- items aliased to @graph
- A vocabulary (via @vocab or prefix like ujg:) ensuring types are resolvable (e.g., Journey or ujg:Journey).
Payload: The items property MUST be an array of Nodes. This array represents the JSON-LD graph.

2.3. Node Integrity and Uniqueness

Identity: Every Node in items[] MUST possess:
- type: A non-empty string.
- id: A non-empty string representing a valid URI/URN.
Uniqueness: No two Nodes within a single document MAY share the same id.
Reserved Keys: The keys @context, type, id, meta, extensions, specVersion, and items are reserved for system use.

3. The Root Object (The Envelope)

The Root Object acts as the container for the graph data and is defined by UJGDocument.

3.1. UJGDocument

UJGDocument: A JSON-LD bundle that serves as the container for the graph data.

It MUST satisfy the following schema:

Field	Requirement	Description
`@context`	`required`	JSON-LD context definitions.
`type`	`required`	Must be `"UJGDocument"`.
`specVersion`	`required`	The version of the UJG Core spec (e.g., `"1.0"`).
`items`	`required`	An array of Universal Nodes.

3.2. Example Envelope

json

 {
  "@context": {
    "@vocab": "[https://ujg.specs.openuji.org/ns#](https://ujg.specs.openuji.org/ns#)",
    "id": "@id",
    "type": "@type",
    "items": "@graph"
  },
  "type": "UJGDocument",
  "specVersion": "1.0",
  "items": [
    {"type": "Journey", "id": "urn:ujg:journey:checkout"},
    {"type": "State", "id": "urn:ujg:state:cart"}
  ]
} 
 {
  "@context": {
    "@vocab": "[https://ujg.specs.openuji.org/ns#](https://ujg.specs.openuji.org/ns#)",
    "id": "@id",
    "type": "@type",
    "items": "@graph"
  },
  "type": "UJGDocument",
  "specVersion": "1.0",
  "items": [
    {"type": "Journey", "id": "urn:ujg:journey:checkout"},
    {"type": "State", "id": "urn:ujg:state:cart"}
  ]
} 

4. The Universal Node

Every object inside items is a Node.

4.1. Node

Node: The first-level unit of the graph.

It MUST satisfy the following schema:

Field	Requirement	Description
`type`	`required`	The object class (e.g., `Journey`, `State`).
`id`	`required`	Unique URI/URN identifier.
`meta`	`optional`	Metadata object (versioning, timestamps).
`extensions`	`optional`	Use case and/or Vendor-specific data.

4.2. Handling Meta & Extensions

Timestamps: Any timestamp within meta MUST adhere to [RFC3339] with timezone information (e.g., Z or +01:00).
Extensions (if present):
Structure: extensions MUST be a Map (represented as a §4.3 JSON object).
Key: Every key in the map MUST be a string representing a unique namespace (e.g., reverse-DNS notation).
Value: The value for every key MUST be a JSON object.

4.3. Example Node

json

 {
  "type": "Journey",
  "id": "urn:ujg:journey:checkout",
  "meta": {
    "created": "2026-02-11T12:00:00Z",
    "version": "v1.2"
  },
  "extensions": {
    "io.security.audit": {
      "checksum": "sha256:abc1234..."
    }
  }
} 
 {
  "type": "Journey",
  "id": "urn:ujg:journey:checkout",
  "meta": {
    "created": "2026-02-11T12:00:00Z",
    "version": "v1.2"
  },
  "extensions": {
    "io.security.audit": {
      "checksum": "sha256:abc1234..."
    }
  }
} 

References

Normative References

[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner, March 1997, Best Current Practice. IETF. https://datatracker.ietf.org/doc/html/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba, May 2017, Best Current Practice. IETF. https://datatracker.ietf.org/doc/html/rfc8174

Informative References

[JSON]: JSON. https://www.rfc-editor.org/rfc/rfc8259
[JSON-LD 1.1.]: JSON 1.1.. https://www.w3.org/TR/2020/REC-json-ld11-20200716/
[RFC3339]: RFC 3339. https://www.rfc-editor.org/rfc/rfc3339