ujg-ed-observability-modeling

name

ujg-ed-observability-modeling

description

Generate, review, correct, and reason about Observability Modeling in User Journey Graph JSON-LD for the Editor's Draft. Use when the task is scoped to Observability module semantics for ObservationBinding, ObservationEvent input modality requirements, accessible-object locators, surface recognition contracts, and SurfaceInstanceResolver or when whole-document modeling crosses this module boundary.

UJG ED Observability Modeling

Skill tree context

Target: Editor's Draft Public spec URL: https://ujg.specs.openuji.org/ed Scope: Observability module semantics for ObservationBinding, ObservationEvent input modality requirements, accessible-object locators, surface recognition contracts, and SurfaceInstanceResolver Module scope: modules/observability

Related generated skills:

• ujg-ed-modeling: whole UJG document modeling across Core, Graph, Surface and Experience, Runtime, Mapping, Metrics, Localization, Observability, Experience Annotation, and optional modules
• ujg-ed-core-modeling: Core module document containers, imports, top-level nodes, and extensions
• ujg-ed-graph-modeling: Graph module topology, journeys, states, transitions, exits, outgoing navigation, and indexes
• ujg-ed-l10n-modeling: Localization module semantics for MessageBundle copy metadata and locale-switch metadata

When the task crosses module boundaries, read references/related-skills.md and references/skill-tree.json before continuing.

UJG ED Observability Modeling

Use this skill together with ujg-ed-modeling. Do not use it as a replacement for the parent modeling skill.

Source of truth

Use the active Editor's Draft unless the user explicitly asks for a dated snapshot:

https://ujg.specs.openuji.org/ed/modules/observability

Generate only terms defined by the active ED Observability context and required bridge modules unless the user explicitly requests an extension.

Scope

Observability defines recognition contracts for Surface nodes. Use it when a surface needs browser, native, synthetic, or adapter-facing recognition through accessibility objects or custom locators.

Use Observability for:

• ObservationBinding nodes that bind recognition evidence to one Surface.
• ObservationEvent contracts such as presence or activation.
• InputModality and InputModalityProfile requirements declared by ObservationEvent nodes.
• AccessibleLocator, AccessibleFeature, and AccessibleRelation definitions.
• SurfaceInstanceResolver rules that identify repeated surface instances from accessible features.
• CustomLocator escape hatches with Core extensions.

Do not use Observability for Graph traversal, Runtime ordering, raw analytics payloads, test scripts, selector-only automation, authorization, server truth, queue state, or protocol state.

Contexts

When using Observability terms, include Core, Surface, Localization, and Observability contexts:

[
  "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/surface.context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/l10n.context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/observability.context.jsonld"
]

Include Runtime context only when serializing actual RuntimeEvent or JourneyExecution nodes. Runtime correlation is derived through RuntimeEvent.surfaceInstanceRef -> SurfaceInstance.surfaceRef -> ObservationBinding.observeSurfaceRef.

Vocabulary

Use only these Observability classes:

ObservationBinding
ObservationEvent
InputModality
InputModalityProfile
AccessibleLocator
AccessibleFeature
AccessibleRelation
CustomLocator
SurfaceInstanceResolver

Use only these Observability properties:

observeSurfaceRef
observationEventRef
requiredInputModalityProfileRefs
inputModalityRefs
locatorRefs
surfaceInstanceResolverRef
instanceKeyFeatureRef
role
accessibleNameRef
accessibleDescriptionRef
accessibleFeatureRefs
accessibleRelationRefs
contextLocatorRefs
accessibleFeatureName
accessibleFeatureValue
accessibleRelationType
targetLocatorRef

Do not invent:

selector
cssSelector
xpath
playwrightLocator
testId
runtimeEventRef
surfaceInstanceRef
observedAt
collectorRef
assertion
apiProbe
waitFor

Use private extensions only on CustomLocator nodes or other UJG nodes for adapter-specific details that are not interoperable Observability semantics.

Binding model

An ObservationBinding must identify exactly one Surface with observeSurfaceRef.

It must identify one ObservationEvent with observationEventRef.

It must list one or more locators with locatorRefs. Locators inside one binding are conjunctive; model alternatives as separate bindings pointing to the same surface.

Input-modality profile references belong to the referenced ObservationEvent, not to ObservationBinding or Graph Transition.

An ObservationEvent may list input-modality profiles with requiredInputModalityProfileRefs.

An InputModalityProfile must list one or more modalities with inputModalityRefs. All referenced modalities participate in that independently evaluable profile. Do not infer ordering from array order.

Use producer-defined IRIs for concrete ObservationEvent and InputModality nodes. Observability defines classes and properties for events, modalities, and profiles; it does not reserve standard event or modality IRIs.

Accessible locators

Prefer AccessibleLocator for human-facing UI. Model accessible-object semantics, not DOM structure, CSS selectors, raw text, or tool-specific query syntax.

An AccessibleLocator must provide at least one of:

role
accessibleNameRef
accessibleDescriptionRef
accessibleFeatureRefs
accessibleRelationRefs
contextLocatorRefs

Use accessibleNameRef and accessibleDescriptionRef to point to Localization MessageBundle nodes.

Use AccessibleFeature for accessibility-model states and properties such as selected, expanded, disabled, checked, pressed, current, invalid, required, busy, or hidden.

Use AccessibleRelation for accessibility-model relations such as controls, labelled-by, described-by, owns, active-descendant, details, or error-message.

Use contextLocatorRefs to scope a locator by surrounding accessible objects. Multiple context locators are conjunctive.

Surface instance resolution

Use SurfaceInstanceResolver when the same stable Surface can appear in repeated concrete occurrences and an adapter needs a stable instance key.

SurfaceInstanceResolver.instanceKeyFeatureRef must point to one AccessibleFeature that supplies the instance key source.

A resolver must not point to concrete SurfaceInstance nodes and must not require one binding per repeated occurrence.

Custom locators

Use CustomLocator when interoperable accessible-object recognition is not enough.

Put adapter-specific semantics in Core extensions. Keep them namespaced and opaque to consumers that do not understand the extension.

Do not promote project-specific selectors or Playwright expressions into Observability vocabulary.

Separation rules

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

Observability has no direct dependency on Runtime. Runtime events do not need to reference ObservationBinding.

Do not model automation commands, screenshots, API probes, timestamps, execution order, payloads, or click facts as Observability terms. Use Runtime for observed events and private extensions for adapter details.

For journey transition modality profile references, model the Graph topology with Graph, attach a Surface to the Transition or OutgoingTransition, bind recognition with ObservationBinding, and put input-modality profile references on the referenced ObservationEvent.

Checks before answering

• Did I include Observability context only when Observability terms are used?
• Does every ObservationBinding identify one Surface?
• Does every binding identify one ObservationEvent?
• Does every binding list at least one locator?
• Are input-modality profile references declared on ObservationEvent, not on ObservationBinding or Graph nodes?
• Does every InputModalityProfile list at least one InputModality?
• Did I use producer-defined concrete event and modality IRIs rather than reserved Observability IRIs?
• Are alternative locator strategies separate bindings rather than one disjunctive binding?
• Do accessible names and descriptions point to MessageBundle nodes?
• Are role, feature, and relation names accessibility-model oriented?
• Does each SurfaceInstanceResolver point to one AccessibleFeature, not a SurfaceInstance?
• Did I keep Runtime correlation derived rather than adding an Observability-to-Runtime reference?
• Did Observability avoid changing Graph traversal or Surface identity?