UJG / UJG 1.0 Release Candidate 1 /
W3C Community Group Draft Report

Observability

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 .

Status
CG-DRAFT
Version
1.0-rc1
Published
2026-07-27
Last Update
2026-07-27
Editors
  • Seva Dolgopolov
Group
User Journal Graph Community Group
Repository
View Source
License
W3C-Software-and-Document

1. Overview

This second-level optional module defines a recognition contract for Surface nodes. It lets producers declare how a visible surface can be recognized by synthetic checks, browser collectors, native collectors, or other observation adapters without changing Graph traversal or Runtime ordering.

Observability depends on [UJG Surface] and [UJG Localization]. A binding points to a Surface and uses localized message bundles when accessible names or descriptions are part of recognition. Concrete runtime occurrence identity is derived by the collector when Runtime data is emitted. When a binding has a SurfaceInstanceResolver, the resolver identifies the accessibility-exposed feature used to derive the concrete instance key.

Observability has no direct dependency on Runtime. When Runtime data is present, a consumer can correlate events to bindings by resolving RuntimeEvent.surfaceInstanceRef to a SurfaceInstance and matching that instance's surfaceRef to ObservationBinding.observeSurfaceRef.

Observation events can also reference input-modality profiles. This lets a producer describe affordance recognition across independently evaluated input strategies while keeping the Graph transition model unchanged. Observability standardizes keyboard and pointer modality identifiers; other modality identifiers remain producer-defined.

2. Terminology

  • ObservationBinding: An addressable recognition contract for one Surface.

  • ObservationEvent: An addressable, owner-defined semantic event contract.

  • InputModality: An addressable input modality. observability:keyboard and observability:pointer are standard modalities; other concrete modality identifiers are producer-defined.

  • InputModalityProfile: An addressable interaction strategy defined by one or more input modalities.

  • AccessibleLocator: A locator that describes an accessible object using accessibility role, localized computed name or description references, state/property features, relations, and context.

  • AccessibleFeature: An accessibility state or property used by an accessible locator.

  • AccessibleRelation: A relationship between accessible objects used by an accessible locator.

  • CustomLocator: An opaque extension-backed locator for adapter-specific matching.

  • SurfaceInstanceResolver: A reusable resolver that identifies how an adapter derives a concrete SurfaceInstance key for repeated occurrences of the same stable Surface.

  • Collector: A runtime observation component that evaluates ObservationBinding nodes against an observed environment, resolves or creates the applicable SurfaceInstance when Runtime data is emitted, and records observed events without changing Graph, Surface, or Observability definitions.

  • Synthetic Runner: A collector that drives or inspects a journey through automated execution, such as a Playwright-based browser test. A synthetic runner may activate accessible objects, match locators, and emit Runtime events, but its automation commands are not modeled as Graph traversal rules or Observability vocabulary.

3. ObservationEvent

An ObservationEvent identifies the semantic event contract a binding observes. Event identifiers are producer-defined; this module does not reserve standard event IRIs.

An event can optionally reference one or more InputModalityProfiles.

classDiagram
  class InputModalityProfile
  class ObservationEvent {
    id
    requiredInputModalityProfileRefs
  }
  ObservationEvent --> "0..*" InputModalityProfile : requiredInputModalityProfileRefs

Example JSON nodes:

4. InputModality

An InputModality identifies one input modality that can participate in an interaction strategy. This module defines two standard input modality identifiers:

  • observability:keyboard: keyboard-based interaction.

  • observability:pointer: pointer-based interaction, including mouse, pen, touch, or equivalent pointing input.

Other concrete modality identifiers are producer-defined.

The standard modality identifiers are declared as InputModality resources by the normative Observability ontology. Producers MAY reference them without serializing duplicate InputModality nodes in a document.

classDiagram
  class InputModality {
    id
  }

Example JSON nodes:

json 
[
  {
    "@id": "observability:keyboard",
    "@type": "InputModality"
  },
  {
    "@id": "observability:pointer",
    "@type": "InputModality"
  }
]
[
  {
    "@id": "observability:keyboard",
    "@type": "InputModality"
  },
  {
    "@id": "observability:pointer",
    "@type": "InputModality"
  }
]

5. InputModalityProfile

An InputModalityProfile identifies one independently evaluable interaction strategy. Its inputModalityRefs values identify the modalities that participate in that strategy.

classDiagram
  class InputModality
  class InputModalityProfile {
    id
    inputModalityRefs
  }
  InputModalityProfile --> "1..*" InputModality : inputModalityRefs

Example JSON node:

json 
{
  "@type": "InputModalityProfile",
  "@id": "urn:ujg:input-modality-profile:keyboard",
  "label": "Keyboard",
  "inputModalityRefs": [
    "observability:keyboard"
  ]
}
{
  "@type": "InputModalityProfile",
  "@id": "urn:ujg:input-modality-profile:keyboard",
  "label": "Keyboard",
  "inputModalityRefs": [
    "observability:keyboard"
  ]
}

6. AccessibleFeature

An AccessibleFeature describes an accessibility state or property used by an AccessibleLocator or SurfaceInstanceResolver.

classDiagram
  class AccessibleFeature {
    id
    accessibleFeatureName
    accessibleFeatureValue
  }

Example JSON node:

json 
{
  "@type": "AccessibleFeature",
  "@id": "urn:ujg:accessible-feature:selected-true",
  "accessibleFeatureName": "selected",
  "accessibleFeatureValue": "true"
}
{
  "@type": "AccessibleFeature",
  "@id": "urn:ujg:accessible-feature:selected-true",
  "accessibleFeatureName": "selected",
  "accessibleFeatureValue": "true"
}

7. AccessibleRelation

An AccessibleRelation describes a relationship between accessible objects used by an AccessibleLocator.

classDiagram
  class AccessibleLocator
  class AccessibleRelation {
    id
    accessibleRelationType
    targetLocatorRef
  }
  AccessibleRelation --> AccessibleLocator : targetLocatorRef

Example JSON node:

json 
{
  "@type": "AccessibleRelation",
  "@id": "urn:ujg:accessible-relation:form-labelled-by-heading",
  "accessibleRelationType": "labelled-by",
  "targetLocatorRef": "urn:ujg:locator:checkout-heading"
}
{
  "@type": "AccessibleRelation",
  "@id": "urn:ujg:accessible-relation:form-labelled-by-heading",
  "accessibleRelationType": "labelled-by",
  "targetLocatorRef": "urn:ujg:locator:checkout-heading"
}

8. AccessibleLocator

An AccessibleLocator describes an accessible object through role, localized name or description references, accessibility features, relations, and optional context locators.

classDiagram
  class MessageMeta
  class AccessibleFeature
  class AccessibleRelation
  class AccessibleLocator {
    id
    role
    accessibleNameRef
    accessibleDescriptionRef
    accessibleFeatureRefs
    accessibleRelationRefs
    contextLocatorRefs
  }
  AccessibleLocator --> MessageMeta : accessibleNameRef
  AccessibleLocator --> MessageMeta : accessibleDescriptionRef
  AccessibleLocator --> "0..*" AccessibleFeature : accessibleFeatureRefs
  AccessibleLocator --> "0..*" AccessibleRelation : accessibleRelationRefs
  AccessibleLocator --> "0..*" AccessibleLocator : contextLocatorRefs

Example JSON node:

json 
{
  "@type": "AccessibleLocator",
  "@id": "urn:ujg:locator:checkout-submit",
  "role": "button",
  "accessibleNameRef": "urn:l10n:message-meta:submit-order"
}
{
  "@type": "AccessibleLocator",
  "@id": "urn:ujg:locator:checkout-submit",
  "role": "button",
  "accessibleNameRef": "urn:l10n:message-meta:submit-order"
}

9. CustomLocator

A CustomLocator is an opaque extension-backed locator for adapter-specific matching when interoperable accessible-object recognition is not enough.

classDiagram
  class CustomLocator {
    id
    extensions
  }

Example JSON node:

json 
{
  "@type": "CustomLocator",
  "@id": "urn:ujg:locator:checkout-submit-test-id",
  "extensions": {
    "com.acme.locator": {
      "testId": "submit-order"
    }
  }
}
{
  "@type": "CustomLocator",
  "@id": "urn:ujg:locator:checkout-submit-test-id",
  "extensions": {
    "com.acme.locator": {
      "testId": "submit-order"
    }
  }
}

10. SurfaceInstanceResolver

A SurfaceInstanceResolver declares which accessible feature supplies the instance key for repeated concrete occurrences of the same stable Surface.

classDiagram
  class AccessibleFeature
  class SurfaceInstanceResolver {
    id
    instanceKeyFeatureRef
  }
  SurfaceInstanceResolver --> AccessibleFeature : instanceKeyFeatureRef

Example JSON node:

json 
{
  "@type": "SurfaceInstanceResolver",
  "@id": "urn:ujg:resolver:cart-line-item",
  "instanceKeyFeatureRef": "urn:ujg:accessible-feature:line-item-sku"
}
{
  "@type": "SurfaceInstanceResolver",
  "@id": "urn:ujg:resolver:cart-line-item",
  "instanceKeyFeatureRef": "urn:ujg:accessible-feature:line-item-sku"
}

11. ObservationBinding

An ObservationBinding binds one Surface to one ObservationEvent and one or more locator nodes that define the recognition evidence.

classDiagram
  class Surface
  class ObservationEvent
  class AccessibleLocator
  class CustomLocator
  class SurfaceInstanceResolver
  class ObservationBinding {
    id
    observeSurfaceRef
    observationEventRef
    locatorRefs
    surfaceInstanceResolverRef
    expectedMatchCount
  }
  ObservationBinding --> Surface : observeSurfaceRef
  ObservationBinding --> ObservationEvent : observationEventRef
  ObservationBinding --> AccessibleLocator : locatorRefs
  ObservationBinding --> CustomLocator : locatorRefs
  ObservationBinding --> SurfaceInstanceResolver : surfaceInstanceResolverRef

Example JSON node:

json 
{
  "@type": "ObservationBinding",
  "@id": "urn:ujg:observation-binding:checkout-submit-presence",
  "observeSurfaceRef": "urn:ujg:surface:checkout-submit",
  "observationEventRef": "urn:ujg:observation-event:presence",
  "locatorRefs": ["urn:ujg:locator:checkout-submit"]
}
{
  "@type": "ObservationBinding",
  "@id": "urn:ujg:observation-binding:checkout-submit-presence",
  "observeSurfaceRef": "urn:ujg:surface:checkout-submit",
  "observationEventRef": "urn:ujg:observation-event:presence",
  "locatorRefs": ["urn:ujg:locator:checkout-submit"]
}

Example absence assertion:

json 
{
  "@type": "ObservationBinding",
  "@id": "urn:ujg:observation-binding:checkout-error-absent",
  "observeSurfaceRef": "urn:ujg:surface:checkout-error",
  "observationEventRef": "urn:ujg:observation-event:presence",
  "locatorRefs": ["urn:ujg:locator:checkout-error"],
  "expectedMatchCount": 0
}
{
  "@type": "ObservationBinding",
  "@id": "urn:ujg:observation-binding:checkout-error-absent",
  "observeSurfaceRef": "urn:ujg:surface:checkout-error",
  "observationEventRef": "urn:ujg:observation-event:presence",
  "locatorRefs": ["urn:ujg:locator:checkout-error"],
  "expectedMatchCount": 0
}

12. Binding Model

The module introduces one canonical interoperable attachment:

  • observability:observeSurfaceRef links an ObservationBinding to one Surface.

An ObservationBinding also identifies:

  • observationEventRef: the semantic event being observed.

  • locatorRefs: one or more locator nodes that define how the surface evidence is recognized.

  • surfaceInstanceResolverRef: an optional resolver for deriving a concrete SurfaceInstance when the same stable surface is repeated.

  • expectedMatchCount: an optional exact cardinality for the full conjunctive locator match.

locatorRefs inside one binding are conjunctive: all referenced locators must match. Alternative recognition strategies SHOULD be modeled as separate ObservationBinding nodes that reference the same surface.

When expectedMatchCount is present, a consumer that evaluates the binding MUST compare the number of objects matching the binding's full locatorRefs contract in the current recognition scope to that exact non-negative integer. expectedMatchCount: 0 means the locator contract is expected to find no matching objects. expectedMatchCount: 1 means exactly one matching object is expected. If expectedMatchCount is omitted, the binding preserves the existing positive recognition semantics without exact cardinality.

One ObservationBinding can describe behavior for many repeated SurfaceInstance occurrences of the same Surface. SurfaceInstanceResolver does not reference concrete SurfaceInstance nodes and MUST NOT require one binding per repeated occurrence.

Input-modality profile references belong to the referenced ObservationEvent, not to ObservationBinding. A binding that references an event with requiredInputModalityProfileRefs uses those event-level profile references without changing its own surface, locator, or instance resolver contract.

Observability does not define graphNodeRef, surfaceRef, surfaceInstanceRef, or touchpoint boundary assignment such as compositeStateRefs. Those are Surface and Runtime terms. Observability does not define Runtime properties.

13. Locator Model

AccessibleLocator is the preferred interoperable locator for human-facing UI. It is based on the accessibility object exposed through an accessibility API, not on DOM structure, CSS selectors, Playwright expressions, or raw text content. WAI-ARIA defines an accessibility API as platform interfaces that expose object and event information to assistive technologies [WAI-ARIA-1.2].

AccessibleLocator.accessibleNameRef and AccessibleLocator.accessibleDescriptionRef reference localized MessageMeta nodes for the computed accessible-object name and description. For web DOM environments, producers and consumers SHOULD compute accessible-object names and descriptions according to [ACCNAME-1.2], then match the computed value against a locale-appropriate Message for the referenced message meta.

Observability does not define standard raw string fallback properties for accessible names or descriptions. Private adapter hints MAY appear in Core extensions, but such hints are not normative Observability terms.

An AccessibleLocator MUST provide at least one of:

  • role

  • accessibleNameRef

  • accessibleDescriptionRef

  • accessibleFeatureRefs

  • accessibleRelationRefs

  • contextLocatorRefs

AccessibleFeature names SHOULD be accessibility-model oriented, such as selected, expanded, disabled, checked, pressed, current, invalid, required, busy, or hidden. Producers SHOULD NOT use raw web-only names such as aria-selected when a platform-neutral state/property name is available.

AccessibleRelation names SHOULD also be accessibility-model oriented, such as controls, labelled-by, described-by, owns, active-descendant, details, or error-message.

contextLocatorRefs scope a locator by another accessible object. Multiple context locators are conjunctive.

CustomLocator is the escape hatch for stable semantic markers, CSS selectors, tool-specific queries, native automation identifiers, CLI patterns, server-log queries, kiosk signals, or other adapter-specific matching. A CustomLocator MUST define its semantics in Core extensions and is opaque to consumers that do not understand that extension.

14. Runtime Correlation

Runtime correlation is derived, not modeled as an Observability-to-Runtime reference.

text 
RuntimeEvent.surfaceInstanceRef -> SurfaceInstance.surfaceRef = ObservationBinding.observeSurfaceRef
RuntimeEvent.surfaceInstanceRef -> SurfaceInstance.surfaceRef = ObservationBinding.observeSurfaceRef

An observation adapter that emits Runtime data SHOULD:

  1. match the binding's locatorRefs;

  2. when expectedMatchCount is present, compare the match count to that exact value;

  3. when surfaceInstanceResolverRef is present, read the resolver's instanceKeyFeatureRef from the matched accessible object or contextual accessible object;

  4. resolve or create the matching SurfaceInstance;

  5. emit the required Runtime surfaceInstanceRef.

For expectedMatchCount: 0, a satisfied absence contract does not provide a matched accessible object for instance resolution. Observability still does not require Runtime events to reference an ObservationBinding.

If an instance key is not exposed through the accessibility API, adapters MUST use CustomLocator or Core extensions for private resolver semantics. Runtime events MUST NOT be required to reference an ObservationBinding.

15. Normative Artifacts

This module is published through the following artifacts:

  • observability.ttl: ontology, published at https://ujg.specs.openuji.org/tr/1.0/ns/observability

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

  • observability.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/tr/1.0/ns/observability.shape

Examples in this page compose the shared baseline context https://ujg.specs.openuji.org/tr/1.0/ns/context.jsonld with the Surface, Localization, and Observability contexts. Runtime appears only in the informative correlation example.

15.1. Ontology

The normative Observability ontology is defined below and is published at https://ujg.specs.openuji.org/tr/1.0/ns/observability.

15.2. JSON-LD Context

The normative Observability JSON-LD context is defined below and is published at https://ujg.specs.openuji.org/tr/1.0/ns/observability.context.jsonld.

15.3. Validation

The normative Observability SHACL shape is defined below and is published at https://ujg.specs.openuji.org/tr/1.0/ns/observability.shape.

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

  1. Surface first: An ObservationBinding MUST identify exactly one Surface using observeSurfaceRef.

  2. No graph traversal: Observability properties MUST NOT change Graph validity, graph traversal behavior, import resolution, or core node identity.

  3. No Runtime dependency: Observability MUST NOT require Runtime data and MUST NOT define a Runtime property.

  4. Derived Runtime correlation: Consumers MAY correlate Runtime events to bindings by matching RuntimeEvent.surfaceInstanceRef -> SurfaceInstance.surfaceRef to ObservationBinding.observeSurfaceRef.

  5. Conjunctive locators: locatorRefs inside one ObservationBinding are conjunctive.

  6. Exact match counts: When expectedMatchCount is present on an ObservationBinding, consumers that evaluate the binding MUST compare the number of objects matching the full conjunctive locator contract in the current recognition scope to that exact non-negative integer. expectedMatchCount: 0 means the locator contract is expected to find no matching objects. When expectedMatchCount is omitted, consumers MUST NOT infer exact cardinality from the binding.

  7. Event-level modality profiles: Input-modality profile references MUST be declared on ObservationEvent with requiredInputModalityProfileRefs, not on ObservationBinding or Graph Transition nodes.

  8. Profile modality references: InputModalityProfile.inputModalityRefs values identify InputModality nodes. Consumers MUST NOT infer interaction order from the order of values.

  9. Standard and owner-defined modality IRIs: Event identifiers remain producer-defined. Observability reserves observability:keyboard and observability:pointer as standard InputModality identifiers; producers define other concrete modality identifiers.

  10. Instance resolver: SurfaceInstanceResolver.instanceKeyFeatureRef MUST identify one AccessibleFeature that supplies the instance key source. A resolver MUST NOT reference concrete SurfaceInstance nodes.

  11. Accessible-object semantics: AccessibleLocator identifies an accessible object, not an implementation node or selector expression.

  12. Localized name and description matching: accessibleNameRef and accessibleDescriptionRef MUST resolve to MessageMeta nodes. In web DOM environments, adapters SHOULD compute accessible names and descriptions according to [ACCNAME-1.2], then match the computed values against locale-appropriate Message values for those message metas.

  13. Accessibility API orientation: Role, feature, and relation names SHOULD describe accessibility API concepts rather than DOM or tool-specific implementation details [WAI-ARIA-1.2].

  14. Opaque custom locators: CustomLocator semantics live in Core extensions; consumers that do not understand the extension MAY ignore the locator semantics.

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

16. Examples

16.1. Minimal Example

16.2. Input Modality Requirement Example

This example shows a producer-defined activation event for a transition affordance surface. The event references two producer-defined modality profiles that use standard keyboard and pointer modality identifiers.

16.3. Runtime Correlation Example

The runtime event can be correlated to urn:binding:bob-pending-share-present because its referenced surface instance points back to urn:surface:bob-pending-share. The event does not reference the binding.