Seam predicates

Generated page

This page is generated from ontology/seam.ttl on every docs build, so it always matches the file CI validates.

SemanticSeams Bridging Ontology. The cross-layer predicates that weld architecture, UI, process, decision, state, data, communication, authorization, and planning models into one navigable graph. Design rules: (1) few and generic beats many and precise; (2) every predicate must earn a cross-layer query; (3) reuse existing vocabularies inside layers, mint here only where layers meet; (4) the navigation backbone stays notation-agnostic.

Each predicate is described in the order and grouping of the ontology file. Constraints on how the predicates may be used live in the SHACL shapes, not in rdfs:domain or rdfs:range, so most predicates below state their intended source and target in their description.

Navigation backbone

seam:Model

Class · Model.

A diagram/model in some notation; typically stored as its own named graph.

seam:detailedBy

Predicate · detailed by.

Focus element -> model that elaborates it. Traversing this edge is 'zooming in'.

Range: seam:Model · Reveal: open

seam:notation

Predicate · notation.

Which renderer the shell mounts for this model.

Domain: seam:Model · Range: seam:Notation

seam:inModel

Predicate · in model.

Element -> the seam:Model it belongs to. Membership as DATA: the fragment-IRI convention (:order_bpmn#persist_task) is a rendering-dispatch naming scheme that SPARQL cannot traverse; this edge is what cross-layer property paths walk (e.g. process -> seam:detailedBy -> model -> ^seam:inModel -> task). Asserted for every lifted element. For elements whose triples are native RDF (IFML, states, shapes), it is asserted alongside layer containment until named-graph partitioning (ADR-0001) lands. Earns every query that crosses a model boundary.

Range: seam:Model

seam:Notation

Class · Notation.

seam:renderPayload

Predicate · render payload.

Link to (or literal containing) the native serialization used for rendering, e.g. BPMN 2.0 XML or DMN XML. Native payloads are kept as-is; only seam-participating elements are lifted to IRIs. Convention: native element IDs become IRI fragments on the model IRI, e.g. :order_bpmn#persist_task.

Domain: seam:Model

Value	Kind	Meaning
seam:C4	seam:Notation	C4-style architecture view
seam:IFML	seam:Notation	IFML interaction model
seam:BPMN	seam:Notation	BPMN 2.0 process diagram
seam:DMN	seam:Notation	DMN decision model
seam:Statechart	seam:Notation	Harel statechart
seam:ShapeGraph	seam:Notation	RDF/SHACL data-model view
seam:Ontology	seam:Notation	OWL ontology (classes and properties)

Reveal modes

seam:RevealMode

Class · Reveal mode.

How the viewer reveals a seam edge's target when the source is clicked (docs/research/2026-10-15-reveal-modes.md section 2, ADR-0005 as amended). Replaces the boolean navigational set: open and nest predicates navigate, layer predicates stay inspector-only until layer mode lands.

seam:reveal

Predicate · reveal.

seam predicate -> its default seam:RevealMode. Every seam predicate except the administrative ones (inModel, notation, renderPayload) declares exactly one (constraint in shapes/seam-shapes.ttl). An annotation, not a seam edge: it describes predicates, never model elements.

Range: seam:RevealMode

Value	Kind	Meaning
seam:Open	seam:RevealMode	open
seam:Nest	seam:RevealMode	nest
seam:Layer	seam:RevealMode	layer

Architecture ↔ everything

seam:presents

Predicate · presents.

arch:Container -> IFML seam:Model. The container's user-facing surface. (Resolved Container per review triage; a Component variant can wait.)

Reveal: nest

seam:exposes

Predicate · exposes.

arch:Container -> comm:Operation | comm:Channel.

Reveal: layer

seam:consumes

Predicate · consumes.

arch:Container -> comm:Operation | comm:Channel. The dependency edge.

Reveal: layer

seam:deployedTo

Predicate · deployed to.

arch:Container -> arch:DeploymentNode. Enables 'what breaks if db02 goes away'.

Reveal: layer

seam:executes

Predicate · executes.

arch:Container -> proc:Process it runs. Completes impact analysis: 'what breaks if node X dies' must reach the process layer, and the generic graph-literate worker needs to know where a task's process lives.

Reveal: nest

seam:schedules

Predicate · schedules.

arch:Container -> proc:Process whose timer start events it runs (ADR-0037). The container also seam:executes the process, since it starts each instance in process. Exactly one per process whose BPMN model holds a proc:TimerStartEvent; listed, never derived from seam:executes, because a process may be executed by more than one container and the one that keeps time is a decision. Earns the query "which schedules stop if node X dies" (seam:schedules/seam:deployedTo). (Constraints in shapes/seam-shapes.ttl.)

Reveal: nest

seam:owns

Predicate · owns.

A bounded context owns a model: the model is written in the context's language and changed by its team.

Domain: arch:BoundedContext · Range: seam:Model · Reveal: layer

Data ↔ architecture

seam:storedIn

Predicate · stored in.

sh:NodeShape -> arch:Container (a store) that persists its instances. Lets impact-of-node.rq answer which data is lost if a node goes away (ADR-0011). (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

UI ↔ process

seam:triggers

Predicate · triggers.

ifml:Event -> proc:Process | dec:Decision. IFML's action-reference extension point, made concrete.

Reveal: open

seam:completedOn

Predicate · completed on.

proc:UserTask -> ifml:Form on which a person completes the task, at most one per task (ADR-0009, decision D027). The mirror of seam:triggers: an event starts a process, a user task waits for a form. The screen is the ifml:ViewContainer that ifml:contains the form; the form's one event seam:submitsTo the completion operation, and the form seam:writes the task's output shape. Authorization: the task's seam:governedBy policies are evaluated with the task IRI as the odrl:target; an ungoverned task is open to any authenticated identity. Earns the query 'which screens must a person visit to finish this process' (docs/queries/screens-to-finish-process.rq). (Constraint in shapes/seam-shapes.ttl.)

Reveal: open

seam:visibleWhen

Predicate · visible when.

ifml:ViewComponent -> state:State. Conditional rendering as a graph edge. Multi-valued: the component is visible when the state is any one of its values. Evaluation rule: the guard is evaluated server-side, at render time, against the lifecycle of the shape the component seam:reads (the shape's effective lifecycle: its own seam:lifecycle, else that of its sh:targetClass, ADR-0031; the machine must state:hasState every guard state). The template variable is the shape's local name, lowercased, minus a trailing 'shape', plus '_state' (:MessageShape -> message_state), compared with the guard state's rdfs:label (one state: ==, several: in a tuple of the labels, sorted). The value is the state of the current instance in the component's render context (for the message thread, the conversation's latest message). A state change re-renders the component through the channel events the client consumes (comm:eventName on a seam:consumes channel); no client-side guard.

Reveal: layer

UI ↔ communication

seam:submitsTo

Predicate · submits to.

ifml:Event -> hydra:Operation the event calls (the form's hx-post, the FastAPI route). seam:triggers names the process the event starts; the operation's handler starts it. Earns the query 'which route does this UI event call, and which policies must that route enforce' (event -> seam:submitsTo -> operation -> seam:governedBy). (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

seam:rendersComponent

Predicate · renders component.

hydra:Operation -> ifml:ViewComponent whose partial is the operation's seam:UIFragment response. The template name derives from the component (ADR-0007 component -> partial): <component>.html when the flow that lands the response swaps ifml:Replace, <component>_item.html when it swaps ifml:Append or ifml:Prepend. The inverse earns 'which endpoint loads or updates this component' (the hx-get of a list or details). (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

Process ↔ decisions, communication, data

seam:decidedBy

Predicate · decided by.

proc business-rule task -> dec:Decision.

Reveal: open

seam:invokes

Predicate · invokes.

proc service task -> comm:Operation.

Reveal: layer

seam:publishesTo

Predicate · publishes to.

proc message throw event (completion event, named by the channel's rdfs:label) | proc service task that seam:invokes an operation (each streamed delta of that operation's reply, named by comm:eventName) | state:Transition (the domain event the transition is, named by its IRI or state:trigger, never a copied label; ADR-0031) -> comm:Channel.

Reveal: layer

seam:subscribesTo

Predicate · subscribes to.

proc message catch event -> comm:Channel. On a process's start event it makes the process channel-started: each publish on the channel starts an instance (ADR-0010).

Reveal: layer

seam:reads

Predicate · reads.

task | view component | decision -> sh:NodeShape it reads. Workhorse of impact analysis. (Constraint lives in shapes/seam-shapes.ttl, not rdfs:range: RDFS ranges infer, they don't reject.)

Reveal: layer

seam:writes

Predicate · writes.

task | ui event -> sh:NodeShape it writes. Workhorse of impact analysis. (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

Data ↔ lifecycle

seam:lifecycle

Predicate · lifecycle.

owl:Class | sh:NodeShape -> state:StateMachine governing instances of the class or the shape. The class is preferred; a shape's effective lifecycle is its own, else that of its sh:targetClass, and more than one is a violation (ADR-0031). (Constraint in shapes/seam-shapes.ttl.)

Reveal: open

seam:aggregateMember

Predicate · aggregate member.

aggregate (an owl:Class or sh:NodeShape with a seam:lifecycle) -> sh:NodeShape whose entities the aggregate commits together, in one store transaction. Listed, never derived from sh:targetClass; a shape is a member of at most one aggregate (ADR-0035). (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

seam:fires

Predicate · fires.

proc task -> state:Transition. Inverse view: which tasks may move an Order out of 'submitted'?

Reveal: layer

Communication contracts

seam:acceptsShape

Predicate · accepts shape.

operation | channel -> request / event payload sh:NodeShape. (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

seam:returnsShape

Predicate · returns shape.

operation -> response payload sh:NodeShape. For operations whose seam:mediaKind is seam:UIFragment, this describes the shape of the DATA the fragment renders, not the HTTP body (which is HTML). On a hydra:Status that an operation hydra:possibleStatus (an error with a comm:errorCode), it is the error shape: the problem+json body of that response (ADR-0013). (Constraint in shapes/seam-shapes.ttl.)

Reveal: layer

seam:implementedBy

Predicate · implemented by.

operation -> the implementation that serves it (ADR-0012). The node's rdf:type is its kind: comm:LLMCompletion, comm:PythonHandler or comm:HTTPEndpoint. At most one per operation; every task that invokes the operation gets the same implementation. An operation invoked across containers must declare one; an in-process operation with none is served by the runtime itself. Layer reveal: the implementation is code, not a model the viewer opens. (Constraints in shapes/seam-shapes.ttl.)

Domain: hydra:Operation · Reveal: layer

seam:catches

Predicate · catches.

proc:ErrorBoundaryEvent -> the hydra:Status it catches: one error (comm:errorCode) of the operation its task seam:invokes (ADR-0013). When the operation's implementation raises that error, the runtime routes the process down the boundary's outgoing flow instead of failing the instance. Exactly one per boundary. Layer reveal: the status is part of the operation's contract, not a model of its own. (Constraints in shapes/seam-shapes.ttl.)

Reveal: layer

seam:mediaKind

Predicate · media kind.

operation -> seam:UIFragment | seam:Data. The htmx two-kinds-of-API distinction.

Range: seam:MediaKind · Reveal: layer

seam:MediaKind

Class · Media kind.

Value	Kind	Meaning
seam:UIFragment	seam:MediaKind	hypermedia / UI fragment response
seam:Data	seam:MediaKind	pure data (JSON-LD) response

Authorization (cross-cutting by design)

seam:governedBy

Predicate · governed by.

ANY element -> policy (odrl:Policy, or an ACP/WebACL resource — hence no rdfs:range, which would wrongly INFER odrl:Policy on a WebACL resource). Deliberately broad domain: attaches to events, tasks, operations, shapes, transitions alike. Propagation rule (documented, not enforced in v1): an action is allowed iff every edge on the UI-event -> ... -> shape path carries either no policy or a satisfied one.

Reveal: layer

Profiles and planning (reserved seams)

seam:Profile

Class.

A methodology profile: a component taxonomy plus a SHACL shapes library validating the model graph itself (e.g. IDesign).

seam:conformsTo

Predicate · conforms to.

Range: seam:Profile · Reveal: layer

seam:offersClass

Predicate · offers class.

Profile -> a class the editor offers when adding an element, one triple per class (ADR-0018). Stated in the profile's profile.ttl, never in the model. Labels for the offered class come from skos:prefLabel, else rdfs:label, in the same file.

Domain: seam:Profile · Reveal: layer

seam:usesGenerator

Predicate · uses generator.

Profile -> the name (a string) of a generator the editor previews: a seams.generators entry-point name as written in seams.toml (ADR-0016, ADR-0018).

Domain: seam:Profile · Reveal: layer

seam:profileShapes

Predicate · profile shapes.

Profile -> a shapes file (a string path relative to the profile directory) merged into the viewer's health check (ADR-0018).

Domain: seam:Profile · Reveal: layer

seam:realizes

Predicate · realizes.

plan:Activity -> ANY element. The single edge the Gantt projection needs.

Reveal: layer