Routing

incubating

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 optional module defines a graph-native vocabulary for attaching routing metadata to UJG nodes. It lets a producer bind any addressable node to a reusable Route resource through routing:routeRef instead of hiding route names, path templates, or fallback targets inside opaque Core extensions.

This module is optional. It annotates the shared graph with routing resources, but it does not change graph topology, traversal rules, or import resolution.

2. Normative Artifacts

This module is published through the following artifacts:

routing.ttl: ontology, published at https://ujg.specs.openuji.org/ed/ns/routing
routing.context.jsonld: JSON-LD term mappings, published at https://ujg.specs.openuji.org/ed/ns/routing.context.jsonld
routing.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/ed/ns/routing.shape

Examples in this page compose the shared baseline context https://ujg.specs.openuji.org/ed/ns/context.jsonld with the Routing context.

Non-goals:

This module does not define router execution, redirect policies, or platform-specific path matching.
This module does not introduce new traversal semantics beyond [UJG Graph].
This module does not replace opaque vendor-private hints carried in [UJG Core] extensions.

3. Terminology

Route: An addressable routing resource that carries path, deep-link, and fallback metadata.

4. Attachment Model

The module introduces real JSON-LD terms and RDF edges for routing attachment:

routing:routeRef links any UJG node to a Route.
routing:fallbackNodeRef links a Route to a fallback UJG node.

The module also defines non-reference properties such as routing:routeName, routing:path, routing:deepLink, routing:guards, and JSON-valued routing:params.

5. Ontology

The normative Routing ontology is defined below and is published at https://ujg.specs.openuji.org/ed/ns/routing. It is the authoritative structural definition for Route and the properties declared by this module.

turtle

 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgrouting: <https://ujg.specs.openuji.org/ed/ns/routing#> .
@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/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

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

### Classes

ujgrouting:Route a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgrouting:routeRef a owl:ObjectProperty ;
  rdfs:domain ujg:Node ;
  rdfs:range ujgrouting:Route .

ujgrouting:fallbackNodeRef a owl:ObjectProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range ujg:Node .

ujgrouting:routeName a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:path a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:deepLink a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:guards a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:params a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range rdf:JSON . 
 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgrouting: <https://ujg.specs.openuji.org/ed/ns/routing#> .
@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/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

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

### Classes

ujgrouting:Route a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgrouting:routeRef a owl:ObjectProperty ;
  rdfs:domain ujg:Node ;
  rdfs:range ujgrouting:Route .

ujgrouting:fallbackNodeRef a owl:ObjectProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range ujg:Node .

ujgrouting:routeName a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:path a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:deepLink a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:guards a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range xsd:string .

ujgrouting:params a owl:DatatypeProperty ;
  rdfs:domain ujgrouting:Route ;
  rdfs:range rdf:JSON . 

6. JSON-LD Context

The normative Routing JSON-LD context is defined below and is published at https://ujg.specs.openuji.org/ed/ns/routing.context.jsonld. It provides the compact JSON-LD term mappings and coercions for Routing-specific properties and classes.

json-ld

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

    "ujgrouting": "https://ujg.specs.openuji.org/ed/ns/routing#",
    "routing": "https://ujg.specs.openuji.org/ed/ns/routing#",

    "Route": "ujgrouting:Route",

    "routeRef": {
      "@id": "ujgrouting:routeRef",
      "@type": "@id"
    },
    "fallbackNodeRef": {
      "@id": "ujgrouting:fallbackNodeRef",
      "@type": "@id"
    },
    "routeName": "ujgrouting:routeName",
    "path": "ujgrouting:path",
    "deepLink": "ujgrouting:deepLink",
    "guards": {
      "@id": "ujgrouting:guards",
      "@container": "@set"
    },
    "params": {
      "@id": "ujgrouting:params",
      "@type": "@json"
    }
  }
} 
 {
  "@context": {
    "@version": 1.1,

    "ujgrouting": "https://ujg.specs.openuji.org/ed/ns/routing#",
    "routing": "https://ujg.specs.openuji.org/ed/ns/routing#",

    "Route": "ujgrouting:Route",

    "routeRef": {
      "@id": "ujgrouting:routeRef",
      "@type": "@id"
    },
    "fallbackNodeRef": {
      "@id": "ujgrouting:fallbackNodeRef",
      "@type": "@id"
    },
    "routeName": "ujgrouting:routeName",
    "path": "ujgrouting:path",
    "deepLink": "ujgrouting:deepLink",
    "guards": {
      "@id": "ujgrouting:guards",
      "@container": "@set"
    },
    "params": {
      "@id": "ujgrouting:params",
      "@type": "@json"
    }
  }
} 

7. Validation

The normative Routing SHACL shape is defined below and is published at https://ujg.specs.openuji.org/ed/ns/routing.shape. It is the authoritative validation artifact for Routing structural constraints.

turtle

 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgrouting: <https://ujg.specs.openuji.org/ed/ns/routing#> .
@prefix ujgroutingshape: <https://ujg.specs.openuji.org/ed/ns/routing.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ujgroutingshape:NodeRouteShape a sh:NodeShape ;
  sh:targetClass ujg:Node ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgrouting:routeRef ;
    sh:class ujgrouting:Route ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgroutingshape:RouteShape a sh:NodeShape ;
  sh:targetClass ujgrouting:Route ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgrouting:routeName ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:path ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:deepLink ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:guards ;
    sh:datatype xsd:string ;
  ] ;

  sh:property [
    sh:path ujgrouting:params ;
    sh:datatype rdf:JSON ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:fallbackNodeRef ;
    sh:class ujg:Node ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] . 
 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgrouting: <https://ujg.specs.openuji.org/ed/ns/routing#> .
@prefix ujgroutingshape: <https://ujg.specs.openuji.org/ed/ns/routing.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ujgroutingshape:NodeRouteShape a sh:NodeShape ;
  sh:targetClass ujg:Node ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgrouting:routeRef ;
    sh:class ujgrouting:Route ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgroutingshape:RouteShape a sh:NodeShape ;
  sh:targetClass ujgrouting:Route ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgrouting:routeName ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:path ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:deepLink ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:guards ;
    sh:datatype xsd:string ;
  ] ;

  sh:property [
    sh:path ujgrouting:params ;
    sh:datatype rdf:JSON ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgrouting:fallbackNodeRef ;
    sh:class ujg:Node ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] . 

The rules below define the remaining module semantics beyond the structural constraints captured by the SHACL shape.

Attachment only: Routing properties MUST NOT change Graph validity, graph traversal behavior, import resolution, or core node identity.
Fallback resolution: Every routing:fallbackNodeRef MUST resolve to a UJG node within the current scope or imported modules.
Graceful degradation: A consumer that does not implement this module MAY ignore Routing semantics, but it SHOULD preserve recognized JSON-LD data during read-transform-write when possible.
Private runtime hints: Platform-specific router configuration that is not intended for shared queryability or validation SHOULD remain in Core extensions.

8. Appendix: Combined JSON Example

json

 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/routing.context.jsonld"
  ],
  "@id": "https://example.com/ujg/routing/checkout.jsonld",
  "@type": "UJGDocument",
  "specVersion": "1.0",
  "nodes": [
    {
      "@type": "State",
      "@id": "urn:ujg:state:checkout.shipping",
      "label": "Shipping",
      "routing:routeRef": "urn:routing:route:checkout-shipping"
    },
    {
      "@type": "State",
      "@id": "urn:ujg:state:cart",
      "label": "Cart"
    },
    {
      "@type": "routing:Route",
      "@id": "urn:routing:route:checkout-shipping",
      "routing:routeName": "checkout-shipping",
      "routing:path": "/checkout/shipping",
      "routing:deepLink": "myapp://checkout/shipping",
      "routing:guards": ["cart-not-empty", "user-authenticated"],
      "routing:params": {
        "market": ":market",
        "locale": ":locale"
      },
      "routing:fallbackNodeRef": "urn:ujg:state:cart"
    }
  ]
} 
 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/routing.context.jsonld"
  ],
  "@id": "https://example.com/ujg/routing/checkout.jsonld",
  "@type": "UJGDocument",
  "specVersion": "1.0",
  "nodes": [
    {
      "@type": "State",
      "@id": "urn:ujg:state:checkout.shipping",
      "label": "Shipping",
      "routing:routeRef": "urn:routing:route:checkout-shipping"
    },
    {
      "@type": "State",
      "@id": "urn:ujg:state:cart",
      "label": "Cart"
    },
    {
      "@type": "routing:Route",
      "@id": "urn:routing:route:checkout-shipping",
      "routing:routeName": "checkout-shipping",
      "routing:path": "/checkout/shipping",
      "routing:deepLink": "myapp://checkout/shipping",
      "routing:guards": ["cart-not-empty", "user-authenticated"],
      "routing:params": {
        "market": ":market",
        "locale": ":locale"
      },
      "routing:fallbackNodeRef": "urn:ujg:state:cart"
    }
  ]
} 

9. Appendix: Opaque Runtime Hints

json

 {
  "@id": "urn:routing:route:checkout-shipping",
  "@type": "routing:Route",
  "routing:routeName": "checkout-shipping",
  "routing:path": "/checkout/shipping",
  "extensions": {
    "com.acme.router": {
      "prefetch": "intent",
      "cachePolicy": "stale-while-revalidate"
    }
  }
} 
 {
  "@id": "urn:routing:route:checkout-shipping",
  "@type": "routing:Route",
  "routing:routeName": "checkout-shipping",
  "routing:path": "/checkout/shipping",
  "extensions": {
    "com.acme.router": {
      "prefetch": "intent",
      "cachePolicy": "stale-while-revalidate"
    }
  }
} 