UJG / Editor's Draft /
W3C Community Group Draft Report

Action

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 .

Last Update
2026-06-09
Editors
  • Seva Dolgopolov
Group
User Journal Graph Community Group
Repository
View Source
License
W3C-Software-and-Document

1. Overview

This optional module defines a minimal graph-native vocabulary for attaching declared side effects to Graph Transition and OutgoingTransition nodes.

Without an action primitive, implementations tend to hide form submission, API invocation, analytics events, or navigate-with-payload behavior in opaque extensions. That makes a graph appear to advance while the effect that caused the transition remains non-portable.

This first version is intentionally small. It declares that an effective transition has an associated Action; it does not define transport protocols, API request formats, queues, form libraries, analytics payloads, backend workers, or framework event handlers.

2. Normative Artifacts

This module is published through the following artifacts:

  • action.ttl: ontology, published at https://ujg.specs.openuji.org/ed/ns/action

  • action.context.jsonld: JSON-LD term mappings, published at https://ujg.specs.openuji.org/ed/ns/action.context.jsonld

  • action.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/ed/ns/action.shape

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

3. Terminology

  • Action: An addressable declaration of a side effect associated with a Graph transition edge.

  • Action attachment: The relation that assigns a transition to an action declaration.

4. Attachment Model

The module introduces one canonical interoperable attachment:

  • action:actionRef links a Graph Transition or OutgoingTransition to an Action.

A transition without actionRef remains fully valid and traversable. Consumers MAY ignore this module and still process the graph.

5. Ontology

The normative Action ontology is defined below and is published at https://ujg.specs.openuji.org/ed/ns/action.

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

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

### Classes

ujgaction:Action a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgaction:actionRef a owl:ObjectProperty ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf ( ujggraph:Transition ujggraph:OutgoingTransition )
  ] ;
  rdfs:range ujgaction:Action .
@prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgaction: <https://ujg.specs.openuji.org/ed/ns/action#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dct: <http://purl.org/dc/terms/> .

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

### Classes

ujgaction:Action a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgaction:actionRef a owl:ObjectProperty ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf ( ujggraph:Transition ujggraph:OutgoingTransition )
  ] ;
  rdfs:range ujgaction:Action .

6. JSON-LD Context

The normative Action JSON-LD context is defined below and is published at https://ujg.specs.openuji.org/ed/ns/action.context.jsonld.

json-ld 
{
  "@context": {
    "@version": 1.1,

    "ujgaction": "https://ujg.specs.openuji.org/ed/ns/action#",
    "action": "https://ujg.specs.openuji.org/ed/ns/action#",

    "Action": "ujgaction:Action",

    "actionRef": {
      "@id": "ujgaction:actionRef",
      "@type": "@id"
    }
  }
}
{
  "@context": {
    "@version": 1.1,

    "ujgaction": "https://ujg.specs.openuji.org/ed/ns/action#",
    "action": "https://ujg.specs.openuji.org/ed/ns/action#",

    "Action": "ujgaction:Action",

    "actionRef": {
      "@id": "ujgaction:actionRef",
      "@type": "@id"
    }
  }
}

7. Validation

The normative Action SHACL shape is defined below and is published at https://ujg.specs.openuji.org/ed/ns/action.shape.

turtle 
@prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgaction: <https://ujg.specs.openuji.org/ed/ns/action#> .
@prefix ujgactionshape: <https://ujg.specs.openuji.org/ed/ns/action.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .

ujgactionshape:TransitionActionShape a sh:NodeShape ;
  sh:targetClass ujggraph:Transition, ujggraph:OutgoingTransition ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgaction:actionRef ;
    sh:class ujgaction:Action ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgactionshape:ActionShape a sh:NodeShape ;
  sh:targetClass ujgaction:Action ;
  sh:nodeKind sh:IRI .
@prefix ujggraph: <https://ujg.specs.openuji.org/ed/ns/graph#> .
@prefix ujgaction: <https://ujg.specs.openuji.org/ed/ns/action#> .
@prefix ujgactionshape: <https://ujg.specs.openuji.org/ed/ns/action.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .

ujgactionshape:TransitionActionShape a sh:NodeShape ;
  sh:targetClass ujggraph:Transition, ujggraph:OutgoingTransition ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgaction:actionRef ;
    sh:class ujgaction:Action ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgactionshape:ActionShape a sh:NodeShape ;
  sh:targetClass ujgaction:Action ;
  sh:nodeKind sh:IRI .

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

  1. Declaration only: Action describes that a transition edge has an associated side effect; it does not define how that effect is invoked.

  2. Graph preservation: actionRef MUST NOT create a hidden edge or change the from/to semantics of the host Transition or OutgoingTransition.

  3. Graceful degradation: Consumers that do not implement this module MAY ignore Action semantics, but SHOULD preserve recognized JSON-LD data during read-transform-write when possible.

  4. Private contracts: Transport, command, mutation, retry, idempotency, and result-handling details SHOULD remain in Core extensions unless a future optional module defines them as interoperable vocabulary.

8. Minimal Example

json 
{
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/action.context.jsonld"
  ],
  "@id": "https://example.com/ujg/action/checkout.jsonld",
  "@type": "UJGDocument",
  "nodes": [
    {
      "@id": "urn:transition:submit-payment",
      "@type": "Transition",
      "from": "urn:state:payment",
      "to": "urn:state:confirmation",
      "actionRef": "urn:action:authorize-payment"
    },
    {
      "@id": "urn:action:authorize-payment",
      "@type": "Action"
    }
  ]
}
{
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/action.context.jsonld"
  ],
  "@id": "https://example.com/ujg/action/checkout.jsonld",
  "@type": "UJGDocument",
  "nodes": [
    {
      "@id": "urn:transition:submit-payment",
      "@type": "Transition",
      "from": "urn:state:payment",
      "to": "urn:state:confirmation",
      "actionRef": "urn:action:authorize-payment"
    },
    {
      "@id": "urn:action:authorize-payment",
      "@type": "Action"
    }
  ]
}