@canonical/anatomy-dsl 0.2.1 → 0.3.0

package/README.md

@@ -30,6 +30,175 @@ node:
 
 Style values are **design token paths** (`spacing/medium`, `color/surface/button`) — forward-slash delimited references resolved at runtime against the active theme. Primitives like `flow` and `center` are used for layout semantics that don't vary across themes.
 
+## Projections
+
+Projections bind the anatomy tree directly to graph data, after the Relay
+fragment-colocation pattern: the tree carries its data requirements the way a
+lens component carries its fragment.
+
+```yaml
+---
+node:
+  uri: global.component.entity-card
+  projection:
+    on: Component            # type condition — the tree is a view over one Component
+  edges:
+    - node:
+        uri: global.subcomponent.entity-card-header
+        projection:
+          field: _meta.title # this node renders the entity's title
+      relation:
+        cardinality: "1"
+        slotName: header
+    - node:
+        uri: global.component.chip
+        projection:
+          field: _meta.title # relative to the traversed Tag
+      relation:
+        cardinality: "0..*"
+        slotName: tags
+        projection:
+          field: documentationStages  # traversal populating the slot
+```
+
+Semantics:
+
+- The **root node's** `projection.on` establishes the data context — the anatomy
+  is a parameterized view over one entity of that GraphQL type, like
+  `fragment EntityCard on Component`. Children inherit the context.
+- `projection.field` on a **relation** is a traversal: the slot is populated
+  from that field of the current context. The DSL names the field only —
+  never `edges.node`. Anatomy cardinality ↔ graph multiplicity is the Relay
+  pattern taken one level further.
+- **Cardinality decomposes against the schema.** The upper bound claims
+  multiplicity: `..1` maps to an object or scalar field, `..*` to a
+  connection or list. The lower bound claims nullability: `0..` tolerates
+  `null`, `1..` requires the provider to always have the value. So
+  `field: _meta.title` may sit under `cardinality: "1"` (title is total in
+  the contract), but a nullable field like `summary` must sit under `0..1`.
+  `1..*` asserts a non-empty list — deliberately stronger than GraphQL can
+  express, and checkable only at runtime.
+- **Mechanism-blindness.** Whether a plural field is a Relay connection
+  (`subcomponents`) or a plain list (`properties`) is a provider mechanism,
+  not an anatomy fact. Consumers discover the shape from the SDL and unwrap
+  `edges { node }` when needed; an anatomy survives a provider promoting a
+  list to a connection unchanged.
+- `projection.on` on a **child node** narrows the traversed entity's type — the
+  analog of an inline fragment. Switch cases carrying different `on` values
+  mirror an interface resolved through inline fragments.
+- `projection.field` on a **node** means the node renders that field's value,
+  as a dot-delimited path relative to the enclosing context (`_meta.title`).
+- A node projection needs at least one of `on` / `field`; a relation projection
+  requires `field` and admits no type condition (narrowing belongs on the
+  child node).
+
+Field names are anchored to the provider schema the docsite runs against
+(compiled with `prefixing: "none"`); the committed SDL is the naming authority.
+
+A fully projected anatomy **derives a GraphQL fragment** mechanically — the
+example above reads as:
+
+```graphql
+fragment EntityCardAnatomy on Component {
+  _meta { title }                        # header node
+  documentationStages {                  # tags relation (connection per SDL)
+    edges { node { _meta { title } } }   #   each chip
+  }
+}
+```
+
+The derivation rules (type conditions, dot-path expansion, connection
+unwrapping, inline fragments) are specified in the API reference §3.10
+*Derived fragment*; a worked gallery of every projection form is in §13, and
+`examples/yaml/entity-card.anatomy.yaml` is the golden example.
+
+## Props (pinned values)
+
+A named node can **pin** props of the component it references — fixing a prop
+value at one tree position:
+
+```yaml
+node:
+  uri: global.component.icon
+  props:
+    icon: chevron-down
+```
+
+This is how icons become idiomatic with zero icon-specific machinery. The
+design system models the icon as a component whose glyph is a required prop
+(`ds:global.component.icon` › `ds:hasProperty [ ds:name "icon" ]`), so icon
+usage in anatomies splits into exactly two cases:
+
+- **Consumer-filled icon slot** — an icon-component edge with a slot and no
+  pin. The consumer chooses the glyph; the anatomy correctly says nothing.
+- **Component-intrinsic icon** — the accordion chevron, the modal close ×, a
+  status glyph: the component's own spec fixes the glyph, and the anatomy
+  pins it.
+
+Semantics:
+
+- Pins live on **named nodes only** — anonymous nodes have no prop surface.
+  This is enforced in the types, the parser, the JSON Schema, and SHACL.
+- The DSL **never defines a prop surface** (names, types, optionality live in
+  the design system ontology); it only asserts values. Whether a pinned prop
+  exists on the component, and whether a value is admissible (e.g. a glyph
+  name in the icon set), are consumer-side checks against the DS graph — the
+  same posture as projection checking against the provider SDL.
+- Values are scalars, coerced to strings — no token paths or fallback arrays.
+  Pins are *values with meaning*, not styles: a theme may reskin what
+  `chevron-down` looks like (asset layer), but never remap which glyph an
+  anatomy means.
+- A **data-driven** value is a projection (`projection: { field: … }`), and a
+  **state-driven** one is a `switch` — pinned props are static by design.
+
+In TTL, pins reify like styles do: `hasProp [ a :Prop ; propName "…" ;
+propValue "…" ]`. See `examples/yaml/status-header.anatomy.yaml` for
+intrinsic icons, a status-glyph switch, and an unpinned consumer slot in one
+anatomy.
+
+## Interaction states
+
+Interaction states re-value style channels — they never add structure. A
+style key takes an `@state` suffix scoping its value to a state; the unmarked
+key is the default state:
+
+```yaml
+styles:
+  interaction.cursor: pointer
+  interaction.cursor@disabled: not-allowed
+  appearance.background: color/fill/default
+  appearance.background@hover: color/fill/default/hover
+  appearance.background@disabled: color/fill/default/disabled
+  appearance.outline@focus: color/focus-ring   # exists only in a state
+```
+
+The state vocabulary is **closed and registry-governed**: `hover`, `active`,
+`focus`, `disabled`, `selected`. Naming follows the industry consensus where
+systems diverge — `active` subsumes Material's *pressed* and Spectrum's
+*down* (and matches Canonical's own token tree); `focus` maps to CSS
+`:focus-visible` (Spectrum's *key-focus*). `@default` is invalid — absence is
+the default. Candidate additions (`checked`, `visited`, `dragged`, `pending`,
+`error`, `read-only`) go through the registry, never by loosening the schema.
+
+The boundaries that keep "state machines out of scope" true:
+
+- **States hold style values only.** A state that changes the tree is not a
+  state — it is a `switch on: internal` case (async-button's
+  idle/loading/success/error). The DSL declares appearance *per* state, never
+  transitions, triggers, or logic.
+- **Gate vs appearance**: `props: { disabled: true }` (or the consumer) puts
+  a node in the disabled state; `…@disabled` styles say how it looks there.
+- The canonical state token is the base token path plus a state leaf segment
+  (`color/fill/default/hover`), matching the token tree. A consumer-side lint
+  checks that a state-leafed token value agrees with its key's `@state`.
+- The grammar reserves repeatable markers for compound states
+  (`@selected@hover`, canonical order: value/control state before user-action
+  state); v1 permits a single `@`.
+
+In TTL, the Style tuple gains one optional dimension:
+`[ styleKey "appearance.background" ; styleState "hover" ; styleValue "…" ]`.
+See `examples/yaml/stateful-button.anatomy.yaml`.
+
 ## Install
 
 ```sh
@@ -111,35 +280,48 @@ All types mirror the [OWL ontology](definitions/ontology.ttl) exactly:
 | `Node` | `NamedNode \| AnonymousNode` (discriminated on `type`) |
 | `Edge` | Reified parent→child relationship |
 | `Relation` | Cardinality and optional slot name |
-| `Style` | Reified key-value tuple |
+| `Style` | Reified key-value tuple, with an optional interaction `state` dimension |
 | `Switch` | Polymorphic position (discriminator: `props \| internal \| override`) |
 | `SwitchCase` | One alternative within a switch |
+| `Projection` | Fragment-style graph binding on a node (`on` type condition and/or `field` path) |
+| `RelationProjection` | Traversal populating a slot (`field` required) |
+| `Prop` | Pinned prop value on a named node (reified name-value tuple) |
 
 ## Repository Structure
 
 ```
 definitions/   Turtle ontology (OWL) + SHACL shapes
 schemas/       JSON Schema for validating .anatomy.yaml files
-docs/          API reference (merged WD404 + WD404.1)
+docs/          API reference (WD404 + WD404.1 + WD404.2 + WD404.3)
 examples/      Example anatomy files (YAML + Turtle pairs)
 src/           TypeScript types, parser, and transform
 ```
 
 ## Scope
 
-The Anatomy DSL describes **structure only**. It does not handle:
+The Anatomy DSL describes **structure**, **graph-data bindings** (projections
+— what data each position renders), **pinned prop values** (props — fixed
+component configuration at a position), and **state-scoped styles**
+(interaction states — how channels re-value per state). It does not handle:
 
-- **Prop mapping** — which props a component accepts and how they map to behaviour
-- **State or state machines** — component states, transitions, or interaction logic
+- **Prop surface definition** — which props a component accepts, their types
+  and optionality live in the design system ontology; the DSL only pins values
+- **State machines** — transitions, triggers, and interaction logic; the DSL
+  declares appearance per state only, and structural state variation is the
+  switch construct's job
 - **Modifier descriptions** — only design token references are supported, not semantic modifier definitions
 
 ## Design Notes
 
 Styles are modelled as reified key-value tuples (`hasStyle [ styleKey "…" ; styleValue "…" ]`). This keeps the ontology open-ended while remaining lossless. Frequently used style keys may be promoted to first-class datatype properties in a future version.
 
+Projections and pinned props reuse the same reification idiom (`hasProjection [ projectionType "…" ; projectionField "…" ]`, `hasProp [ propName "…" ; propValue "…" ]`). Projections attach to both nodes and relations — the reified `Relation` is precisely what makes slot-level traversal annotations possible without changing the `Edge` class; pins attach to named nodes only.
+
 ## Specification Status
 
 | Index   | Title                    | Status         |
 |---------|--------------------------|----------------|
 | [WD404](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf)   | Anatomy DSL              | Approved       |
 | [WD404.1](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf) | Anatomy DSL — Addendum 1 | Pending Review |
+| WD404.2 | Anatomy DSL — Projections | Draft (this repository) |
+| WD404.3 | Anatomy DSL — Prop pinning | Draft (this repository) |

package/definitions/ontology.ttl

@@ -4,13 +4,14 @@
 @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
 @prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
+@prefix graphql: <https://pragma.canonical.com/graphql#> .
 
 # ═══════════════════════════════════════════════════════════════
 # ONTOLOGY DECLARATION
 # ═══════════════════════════════════════════════════════════════
 
 <http://anatomy-dsl.example.org/ontology> a owl:Ontology ;
-    owl:versionInfo "0.2.0" ;
+    owl:versionInfo "0.3.2" ;
     rdfs:label "Anatomy DSL Ontology" ;
     rdfs:comment "Compliant with OWL DL profile" ;
     skos:definition """Meta-model for the Anatomy DSL — a YAML-based language
@@ -19,11 +20,20 @@
     Models anatomy files as trees of nodes connected by reified edges.
     Inspired by the Relay GraphQL connection pattern.
 
-    Consolidates WD404 (core) and WD404.1 (addendum 1).
+    Consolidates WD404 (core), WD404.1 (addendum 1), projections
+    (addendum 2): fragment-style bindings of nodes and relations to
+    graph data, prop pinning (addendum 3): fixed prop values on
+    referenced components, and interaction states (addendum 4):
+    state-scoped style values.
 
     OUT OF SCOPE (matching the DSL itself):
-    - Prop mapping
-    - State or state machines
+    - Prop surface definition — names, types, and optionality of a
+      component's props live in the design system ontology. Pinned prop
+      VALUES are in scope as of addendum 3.
+    - State MACHINES — transitions, triggers, and interaction logic.
+      Appearance PER interaction state is in scope as of addendum 4
+      (styleState); structural state variation remains the Switch
+      construct's job.
     - Modifier descriptions (only token references)
 
     Validation shapes defined in shapes.ttl.""" .
@@ -62,6 +72,23 @@ anatomy:Style a owl:Class ;
     rdfs:label "Style" ;
     skos:definition "A single style declaration binding a property key to a value." .
 
+anatomy:Projection a owl:Class ;
+    rdfs:label "Projection" ;
+    skos:definition """Fragment-style binding to graph data, after the Relay
+    colocation pattern. On a node it declares a type condition (like a
+    fragment's 'on') and/or the field the node renders; on a relation it
+    declares the traversal that populates the slot.""" .
+
+anatomy:Prop a owl:Class ;
+    rdfs:label "Prop" ;
+    skos:definition """A pinned property value: the anatomy fixes one prop of
+    the referenced component at this tree position (e.g. the icon component's
+    'icon' prop pinned to 'chevron-down' for an intrinsic chevron). References
+    a property defined in the design system ontology — the DSL never defines
+    the prop surface itself. Whether the pinned prop exists on the component,
+    and whether the value is admissible, is validated by consumers holding
+    the design system graph.""" .
+
 # ═══════════════════════════════════════════════════════════════
 # SWITCH CONSTRUCT
 # ═══════════════════════════════════════════════════════════════
@@ -126,12 +153,31 @@ anatomy:hasStyle a owl:ObjectProperty ;
     rdfs:range anatomy:Style ;
     skos:definition "Attaches a style declaration to a node." .
 
+anatomy:hasProjection a owl:ObjectProperty ;
+    rdfs:label "has projection" ;
+    rdfs:domain [ a owl:Class ; owl:unionOf ( anatomy:Node anatomy:Relation ) ] ;
+    rdfs:range anatomy:Projection ;
+    skos:definition "Attaches a graph-data projection to a node or relation." .
+
+anatomy:hasProp a owl:ObjectProperty ;
+    rdfs:label "has prop" ;
+    rdfs:domain anatomy:NamedNode ;
+    rdfs:range anatomy:Prop ;
+    skos:definition "Attaches a pinned prop value to a named node. Named nodes only: anonymous nodes have no prop surface to pin." .
+
 # ═══════════════════════════════════════════════════════════════
 # DATATYPE PROPERTIES
 # ═══════════════════════════════════════════════════════════════
 
 anatomy:uri a owl:DatatypeProperty ;
     rdfs:label "uri" ;
+    # `uri` is the structural primary key of every node in a GraphQL projection
+    # of this ontology (one absolute IRI per entity), so an ontology property of
+    # the same name collides with it. The projection names this one
+    # `anatomyUri`; the RDF term is unchanged and every SPARQL query keeps
+    # working. See canonical/pragma-adrs session/B (ruling R-4: a collision is
+    # an error, never a silent rename).
+    graphql:name "anatomyUri" ;
     rdfs:domain anatomy:NamedNode ;
     rdfs:range xsd:string ;
     skos:definition "Unique identifier for a named node within the design system." ;
@@ -188,3 +234,51 @@ anatomy:styleValue a owl:DatatypeProperty ;
                  "spacing/medium" ,
                  "color/surface/primary" ,
                  "color/surface/button?" .
+
+anatomy:styleState a owl:DatatypeProperty ;
+    rdfs:label "style state" ;
+    rdfs:domain anatomy:Style ;
+    rdfs:range xsd:string ;
+    skos:definition """Interaction state this style value applies in. Absent
+    means the default state. Closed vocabulary (hover, active, focus,
+    disabled, selected), governed by registry — 'active' subsumes Material's
+    'pressed' and Spectrum's 'down'; 'focus' maps to CSS :focus-visible
+    (Spectrum's 'key-focus'). States re-value style channels only: they never
+    add structure (that is the Switch construct) and never define transitions
+    or interaction logic (state machines stay out of scope). Authored as an
+    @state suffix on the style key.""" ;
+    skos:example "hover" , "active" , "focus" , "disabled" , "selected" .
+
+anatomy:projectionType a owl:DatatypeProperty ;
+    rdfs:label "projection type" ;
+    rdfs:domain anatomy:Projection ;
+    rdfs:range xsd:string ;
+    skos:definition "GraphQL type condition, like a Relay fragment's 'on'. On a root node it establishes the data context for the tree; on a child it narrows the traversed entity's type, like an inline fragment." ;
+    skos:example "Component" ,
+                 "OntologyClass" ,
+                 "Pattern" .
+
+anatomy:propName a owl:DatatypeProperty ;
+    rdfs:label "prop name" ;
+    rdfs:domain anatomy:Prop ;
+    rdfs:range xsd:string ;
+    skos:definition "Name of the pinned prop, as defined on the referenced component in the design system ontology." ;
+    skos:example "icon" .
+
+anatomy:propValue a owl:DatatypeProperty ;
+    rdfs:label "prop value" ;
+    rdfs:domain anatomy:Prop ;
+    rdfs:range xsd:string ;
+    skos:definition "The fixed value the anatomy pins the prop to." ;
+    skos:example "chevron-down" ,
+                 "checkmark" ,
+                 "spinner" .
+
+anatomy:projectionField a owl:DatatypeProperty ;
+    rdfs:label "projection field" ;
+    rdfs:domain anatomy:Projection ;
+    rdfs:range xsd:string ;
+    skos:definition "Dot-delimited GraphQL field path relative to the enclosing data context. On a node: the field the node renders. On a relation: the traversal populating the slot. Names the field only, never an unwrapping path like edges/node — whether a plural field is a connection or a plain list is a provider mechanism discovered from the schema. The relation's cardinality maps onto the field's shape: upper bound to multiplicity, lower bound to nullability." ;
+    skos:example "_meta.title" ,
+                 "summary" ,
+                 "documentationStages" .

package/definitions/shapes.ttl

@@ -5,7 +5,7 @@
 @prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
 
 # ═══════════════════════════════════════════════════════════════
-# SHACL SHAPES FOR ANATOMY DSL 0.2.0
+# SHACL SHAPES FOR ANATOMY DSL 0.3.2
 # ═══════════════════════════════════════════════════════════════
 #
 # Constraints, patterns, enumerations, and encoding conventions.
@@ -13,13 +13,17 @@
 #
 # Shapes:
 #   SpecificationShape  — root document
-#   NamedNodeShape      — uri required, encoding pattern
-#   AnonymousNodeShape  — role required
+#   NamedNodeShape      — uri required, encoding pattern, props allowed
+#   AnonymousNodeShape  — role required, props forbidden
 #   EdgeShape           — edgeTarget XOR edgeSwitch
-#   RelationShape       — cardinality pattern, optional slotName
+#   RelationShape       — cardinality pattern, optional slotName,
+#                         optional traversal projection (field required)
 #   SwitchShape         — discriminator enum, minimum cases
 #   SwitchCaseShape     — case node required
-#   StyleShape          — reified key-value tuple (one key, one value)
+#   StyleShape          — reified key-value tuple (one key, one value,
+#                         optional closed-vocabulary interaction state)
+#   ProjectionShape     — at least one of projectionType/projectionField
+#   PropShape           — reified name-value tuple (one name, one value)
 # ═══════════════════════════════════════════════════════════════
 
 # ───────────────────────────────────────────────────────────────
@@ -70,6 +74,19 @@ anatomy:NamedNodeShape a sh:NodeShape ;
         sh:path anatomy:role ;
         sh:maxCount 0 ;
         sh:message "NamedNode must not have a role (use AnonymousNode instead)." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:hasProjection ;
+        sh:maxCount 1 ;
+        sh:class anatomy:Projection ;
+        sh:message "NamedNode admits at most one projection." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:hasProp ;
+        sh:class anatomy:Prop ;
+        sh:message "hasProp must point at a Prop." ;
     ] .
 
 # ───────────────────────────────────────────────────────────────
@@ -94,6 +111,19 @@ anatomy:AnonymousNodeShape a sh:NodeShape ;
         sh:path anatomy:uri ;
         sh:maxCount 0 ;
         sh:message "AnonymousNode must not have a uri (use NamedNode instead)." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:hasProjection ;
+        sh:maxCount 1 ;
+        sh:class anatomy:Projection ;
+        sh:message "AnonymousNode admits at most one projection." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:hasProp ;
+        sh:maxCount 0 ;
+        sh:message "Props belong to components: anonymous nodes have no prop surface to pin — use a NamedNode." ;
     ] .
 
 # ───────────────────────────────────────────────────────────────
@@ -161,6 +191,28 @@ anatomy:RelationShape a sh:NodeShape ;
         sh:path anatomy:slotName ;
         sh:maxCount 1 ;
         sh:datatype xsd:string ;
+    ] ;
+
+    # A relation projection is a traversal: the field is mandatory.
+    # Type narrowing belongs on the child node, never on the relation.
+    sh:property [
+        sh:path anatomy:hasProjection ;
+        sh:maxCount 1 ;
+        sh:class anatomy:Projection ;
+        sh:node [
+            a sh:NodeShape ;
+            sh:property [
+                sh:path anatomy:projectionField ;
+                sh:minCount 1 ;
+                sh:message "Relation projections must name the traversal field." ;
+            ] ;
+            sh:property [
+                sh:path anatomy:projectionType ;
+                sh:maxCount 0 ;
+                sh:message "Type narrowing lives on the child node, not the relation." ;
+            ] ;
+        ] ;
+        sh:message "Relation admits at most one projection, and it must be a traversal (projectionField, no projectionType)." ;
     ] .
 
 # ───────────────────────────────────────────────────────────────
@@ -229,4 +281,83 @@ anatomy:StyleShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:datatype xsd:string ;
         sh:message "Style requires exactly one value." ;
+    ] ;
+
+    # Closed v1 vocabulary, registry-governed. Additions go through the
+    # registry (checked, visited, dragged, pending, error, read-only are
+    # candidates), never through loosening this list ad hoc. There is no
+    # "default" state: an absent styleState IS the default.
+    sh:property [
+        sh:path anatomy:styleState ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:in ( "hover" "active" "focus" "disabled" "selected" ) ;
+        sh:message "styleState must be one of: hover, active, focus, disabled, selected (absent = default state)." ;
+    ] .
+
+# ───────────────────────────────────────────────────────────────
+# PROJECTION
+# ───────────────────────────────────────────────────────────────
+
+anatomy:ProjectionShape a sh:NodeShape ;
+    sh:targetClass anatomy:Projection ;
+    rdfs:label "Projection Shape" ;
+    skos:definition "Fragment-style graph binding: a type condition, a field path, or both — never neither." ;
+
+    sh:property [
+        sh:path anatomy:projectionType ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:pattern "^[A-Z][A-Za-z0-9_]*$" ;
+        sh:message "Projection type must be a GraphQL type name (PascalCase)." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:projectionField ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:pattern "^[_A-Za-z][_A-Za-z0-9]*(\\.[_A-Za-z][_A-Za-z0-9]*)*$" ;
+        sh:message "Projection field must be a dot-delimited path of GraphQL field names." ;
+    ] ;
+
+    sh:or (
+        [
+            sh:property [
+                sh:path anatomy:projectionType ;
+                sh:minCount 1 ;
+            ] ;
+        ]
+        [
+            sh:property [
+                sh:path anatomy:projectionField ;
+                sh:minCount 1 ;
+            ] ;
+        ]
+    ) ;
+    sh:message "Projection requires at least one of projectionType or projectionField." .
+
+# ───────────────────────────────────────────────────────────────
+# PROP
+# ───────────────────────────────────────────────────────────────
+
+anatomy:PropShape a sh:NodeShape ;
+    sh:targetClass anatomy:Prop ;
+    rdfs:label "Prop Shape" ;
+    skos:definition "Reified pinned-prop tuple: exactly one name and one value. Whether the prop exists on the referenced component is validated by consumers holding the design system graph, not here." ;
+
+    sh:property [
+        sh:path anatomy:propName ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:pattern "^[a-z][a-zA-Z0-9]*$" ;
+        sh:message "Prop name must be a camelCase identifier as defined on the component." ;
+    ] ;
+
+    sh:property [
+        sh:path anatomy:propValue ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:message "Prop requires exactly one value." ;
     ] .

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/anatomy-dsl",
   "description": "Anatomy DSL meta-model: TypeScript types mirroring the OWL ontology, and a YAML-to-Turtle transform",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -29,6 +29,7 @@
     "@biomejs/biome": "^2.4.6",
     "@canonical/biome-config": "^0.17.1",
     "@canonical/typescript-config": "^0.17.1",
+    "@types/node": "^26.4.0",
     "expect-type": "^1.3.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",

package/dist/esm/index.js

@@ -1,2 +0,0 @@
-export { parseAnatomyYAML } from "./parse.js";
-export { anatomyToTTL } from "./transform.js";

package/dist/esm/parse.js

@@ -1,72 +0,0 @@
-export function parseAnatomyYAML(raw) {
-    const doc = raw;
-    return {
-        root: toNamedNode(doc.node),
-    };
-}
-function toNamedNode(raw) {
-    return {
-        type: "named",
-        uri: raw.uri,
-        ...(raw.styles ? { styles: toStyles(raw.styles) } : {}),
-        ...(raw.edges ? { edges: raw.edges.map(toEdge) } : {}),
-    };
-}
-function toNode(raw) {
-    if ("uri" in raw && raw.uri) {
-        return toNamedNode(raw);
-    }
-    const anon = raw;
-    return {
-        type: "anonymous",
-        role: anon.role,
-        ...(anon.styles ? { styles: toStyles(anon.styles) } : {}),
-        ...(anon.edges ? { edges: anon.edges.map(toEdge) } : {}),
-    };
-}
-function toStyles(raw) {
-    return Object.entries(raw).map(([key, value]) => ({
-        key,
-        value: String(value),
-    }));
-}
-function toEdge(raw) {
-    let target;
-    if (raw.switch) {
-        target = toSwitch(raw.switch);
-    }
-    else if (raw.node) {
-        target = toNode(raw.node);
-    }
-    else if (raw.uri) {
-        target = { type: "named", uri: raw.uri };
-    }
-    else {
-        throw new Error("Edge must have node, uri, or switch");
-    }
-    return {
-        target,
-        relation: toRelation(raw.relation),
-    };
-}
-function toSwitch(raw) {
-    return {
-        discriminator: raw.on,
-        cases: raw.cases.map(toSwitchCase),
-    };
-}
-function toSwitchCase(raw) {
-    if (raw.uri !== undefined) {
-        const node = { type: "named", uri: raw.uri };
-        return { value: raw.uri, node };
-    }
-    const node = toNode(raw.node);
-    const value = node.type === "named" ? node.uri : node.role;
-    return { value, node };
-}
-function toRelation(raw) {
-    return {
-        cardinality: raw.cardinality,
-        ...(raw.slotName ? { slotName: raw.slotName } : {}),
-    };
-}

package/dist/esm/transform.js

@@ -1,116 +0,0 @@
-const PREFIX = "@prefix : <http://anatomy-dsl.example.org/ontology#> .";
-const INDENT = "    ";
-export function anatomyToTTL(spec) {
-    const lines = [PREFIX, ""];
-    lines.push("[] a :Specification ;");
-    lines.push(`${INDENT}:rootNode [`);
-    writeNode(lines, spec.root, 2);
-    lines.push(`${INDENT}] .`);
-    return `${lines.join("\n")}\n`;
-}
-function writeNode(lines, node, depth) {
-    if (node.type === "named") {
-        writeNamedNode(lines, node, depth);
-    }
-    else {
-        writeAnonymousNode(lines, node, depth);
-    }
-    const styles = node.styles ?? [];
-    const edges = node.edges ?? [];
-    if (styles.length > 0) {
-        writeStyles(lines, styles, depth, edges.length === 0);
-    }
-    if (edges.length > 0) {
-        writeEdges(lines, edges, depth);
-    }
-}
-function writeNamedNode(lines, node, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :NamedNode ;`);
-    const hasMore = (node.styles && node.styles.length > 0) ||
-        (node.edges && node.edges.length > 0);
-    lines.push(`${indent}:uri "${node.uri}"${hasMore ? " ;" : ""}`);
-}
-function writeAnonymousNode(lines, node, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :AnonymousNode ;`);
-    const hasMore = (node.styles && node.styles.length > 0) ||
-        (node.edges && node.edges.length > 0);
-    lines.push(`${indent}:role "${node.role}"${hasMore ? " ;" : ""}`);
-}
-function writeStyles(lines, styles, depth, isLast) {
-    const indent = INDENT.repeat(depth);
-    const innerIndent = INDENT.repeat(depth + 1);
-    lines.push(`${indent}:hasStyle`);
-    for (const [i, style] of styles.entries()) {
-        const sep = i < styles.length - 1 ? " ," : isLast ? "" : " ;";
-        lines.push(`${innerIndent}[ :styleKey "${style.key}" ; :styleValue "${style.value}" ]${sep}`);
-    }
-}
-function writeEdges(lines, edges, depth) {
-    const indent = INDENT.repeat(depth);
-    for (const [i, edge] of edges.entries()) {
-        if (i === 0) {
-            lines.push(`${indent}:hasEdge [`);
-        }
-        else {
-            lines.push(`${indent}] , [`);
-        }
-        writeEdge(lines, edge, depth + 1);
-    }
-    lines.push(`${indent}]`);
-}
-function writeEdge(lines, edge, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :Edge ;`);
-    if (isSwitch(edge.target)) {
-        lines.push(`${indent}:edgeSwitch [`);
-        writeSwitch(lines, edge.target, depth + 1);
-        lines.push(`${indent}] ;`);
-    }
-    else {
-        lines.push(`${indent}:edgeTarget [`);
-        writeNode(lines, edge.target, depth + 1);
-        lines.push(`${indent}] ;`);
-    }
-    writeRelation(lines, edge, depth);
-}
-function writeSwitch(lines, sw, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :Switch ;`);
-    lines.push(`${indent}:discriminator "${sw.discriminator}" ;`);
-    for (const [i, sc] of sw.cases.entries()) {
-        if (i === 0) {
-            lines.push(`${indent}:hasCase [`);
-        }
-        else {
-            lines.push(`${indent}] , [`);
-        }
-        writeSwitchCase(lines, sc, depth + 1);
-    }
-    lines.push(`${indent}]`);
-}
-function writeSwitchCase(lines, sc, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :SwitchCase ;`);
-    lines.push(`${indent}:caseNode [`);
-    writeNode(lines, sc.node, depth + 1);
-    lines.push(`${indent}]`);
-}
-function writeRelation(lines, edge, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}:hasRelation [`);
-    const inner = INDENT.repeat(depth + 1);
-    lines.push(`${inner}a :Relation ;`);
-    if (edge.relation.slotName) {
-        lines.push(`${inner}:cardinality "${edge.relation.cardinality}" ;`);
-        lines.push(`${inner}:slotName "${edge.relation.slotName}"`);
-    }
-    else {
-        lines.push(`${inner}:cardinality "${edge.relation.cardinality}"`);
-    }
-    lines.push(`${indent}]`);
-}
-function isSwitch(target) {
-    return "discriminator" in target;
-}

package/dist/esm/types.js

@@ -1 +0,0 @@
-export {};

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export { parseAnatomyYAML } from "./parse.js";
-export { anatomyToTTL } from "./transform.js";
-export type { AnonymousNode, Edge, NamedNode, Node, Relation, Specification, Style, Switch, SwitchCase, } from "./types.js";

package/dist/index.js

@@ -1,2 +0,0 @@
-export { parseAnatomyYAML } from "./parse.js";
-export { anatomyToTTL } from "./transform.js";

package/dist/parse.d.ts

@@ -1,2 +0,0 @@
-import type { Specification } from "./types.js";
-export declare function parseAnatomyYAML(raw: unknown): Specification;

package/dist/parse.js

@@ -1,72 +0,0 @@
-export function parseAnatomyYAML(raw) {
-    const doc = raw;
-    return {
-        root: toNamedNode(doc.node),
-    };
-}
-function toNamedNode(raw) {
-    return {
-        type: "named",
-        uri: raw.uri,
-        ...(raw.styles ? { styles: toStyles(raw.styles) } : {}),
-        ...(raw.edges ? { edges: raw.edges.map(toEdge) } : {}),
-    };
-}
-function toNode(raw) {
-    if ("uri" in raw && raw.uri) {
-        return toNamedNode(raw);
-    }
-    const anon = raw;
-    return {
-        type: "anonymous",
-        role: anon.role,
-        ...(anon.styles ? { styles: toStyles(anon.styles) } : {}),
-        ...(anon.edges ? { edges: anon.edges.map(toEdge) } : {}),
-    };
-}
-function toStyles(raw) {
-    return Object.entries(raw).map(([key, value]) => ({
-        key,
-        value: String(value),
-    }));
-}
-function toEdge(raw) {
-    let target;
-    if (raw.switch) {
-        target = toSwitch(raw.switch);
-    }
-    else if (raw.node) {
-        target = toNode(raw.node);
-    }
-    else if (raw.uri) {
-        target = { type: "named", uri: raw.uri };
-    }
-    else {
-        throw new Error("Edge must have node, uri, or switch");
-    }
-    return {
-        target,
-        relation: toRelation(raw.relation),
-    };
-}
-function toSwitch(raw) {
-    return {
-        discriminator: raw.on,
-        cases: raw.cases.map(toSwitchCase),
-    };
-}
-function toSwitchCase(raw) {
-    if (raw.uri !== undefined) {
-        const node = { type: "named", uri: raw.uri };
-        return { value: raw.uri, node };
-    }
-    const node = toNode(raw.node);
-    const value = node.type === "named" ? node.uri : node.role;
-    return { value, node };
-}
-function toRelation(raw) {
-    return {
-        cardinality: raw.cardinality,
-        ...(raw.slotName ? { slotName: raw.slotName } : {}),
-    };
-}

package/dist/transform.d.ts

@@ -1,2 +0,0 @@
-import type { Specification } from "./types.js";
-export declare function anatomyToTTL(spec: Specification): string;

package/dist/transform.js

@@ -1,114 +0,0 @@
-const PREFIX = "@prefix : <http://anatomy-dsl.example.org/ontology#> .";
-const INDENT = "    ";
-export function anatomyToTTL(spec) {
-    const lines = [PREFIX, ""];
-    lines.push("[] a :Specification ;");
-    lines.push(`${INDENT}:rootNode [`);
-    writeNode(lines, spec.root, 2);
-    lines.push(`${INDENT}] .`);
-    return `${lines.join("\n")}\n`;
-}
-function writeNode(lines, node, depth) {
-    if (node.type === "named") {
-        writeNamedNode(lines, node, depth);
-    }
-    else {
-        writeAnonymousNode(lines, node, depth);
-    }
-    const styles = node.styles ?? [];
-    const edges = node.edges ?? [];
-    if (styles.length > 0) {
-        writeStyles(lines, styles, depth, edges.length === 0);
-    }
-    if (edges.length > 0) {
-        writeEdges(lines, edges, depth);
-    }
-}
-function writeNamedNode(lines, node, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :NamedNode ;`);
-    const hasMore = (node.styles && node.styles.length > 0) || (node.edges && node.edges.length > 0);
-    lines.push(`${indent}:uri "${node.uri}"${hasMore ? " ;" : ""}`);
-}
-function writeAnonymousNode(lines, node, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :AnonymousNode ;`);
-    const hasMore = (node.styles && node.styles.length > 0) || (node.edges && node.edges.length > 0);
-    lines.push(`${indent}:role "${node.role}"${hasMore ? " ;" : ""}`);
-}
-function writeStyles(lines, styles, depth, isLast) {
-    const indent = INDENT.repeat(depth);
-    const innerIndent = INDENT.repeat(depth + 1);
-    lines.push(`${indent}:hasStyle`);
-    for (const [i, style] of styles.entries()) {
-        const sep = i < styles.length - 1 ? " ," : isLast ? "" : " ;";
-        lines.push(`${innerIndent}[ :styleKey "${style.key}" ; :styleValue "${style.value}" ]${sep}`);
-    }
-}
-function writeEdges(lines, edges, depth) {
-    const indent = INDENT.repeat(depth);
-    for (const [i, edge] of edges.entries()) {
-        if (i === 0) {
-            lines.push(`${indent}:hasEdge [`);
-        }
-        else {
-            lines.push(`${indent}] , [`);
-        }
-        writeEdge(lines, edge, depth + 1);
-    }
-    lines.push(`${indent}]`);
-}
-function writeEdge(lines, edge, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :Edge ;`);
-    if (isSwitch(edge.target)) {
-        lines.push(`${indent}:edgeSwitch [`);
-        writeSwitch(lines, edge.target, depth + 1);
-        lines.push(`${indent}] ;`);
-    }
-    else {
-        lines.push(`${indent}:edgeTarget [`);
-        writeNode(lines, edge.target, depth + 1);
-        lines.push(`${indent}] ;`);
-    }
-    writeRelation(lines, edge, depth);
-}
-function writeSwitch(lines, sw, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :Switch ;`);
-    lines.push(`${indent}:discriminator "${sw.discriminator}" ;`);
-    for (const [i, sc] of sw.cases.entries()) {
-        if (i === 0) {
-            lines.push(`${indent}:hasCase [`);
-        }
-        else {
-            lines.push(`${indent}] , [`);
-        }
-        writeSwitchCase(lines, sc, depth + 1);
-    }
-    lines.push(`${indent}]`);
-}
-function writeSwitchCase(lines, sc, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}a :SwitchCase ;`);
-    lines.push(`${indent}:caseNode [`);
-    writeNode(lines, sc.node, depth + 1);
-    lines.push(`${indent}]`);
-}
-function writeRelation(lines, edge, depth) {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}:hasRelation [`);
-    const inner = INDENT.repeat(depth + 1);
-    lines.push(`${inner}a :Relation ;`);
-    if (edge.relation.slotName) {
-        lines.push(`${inner}:cardinality "${edge.relation.cardinality}" ;`);
-        lines.push(`${inner}:slotName "${edge.relation.slotName}"`);
-    }
-    else {
-        lines.push(`${inner}:cardinality "${edge.relation.cardinality}"`);
-    }
-    lines.push(`${indent}]`);
-}
-function isSwitch(target) {
-    return "discriminator" in target;
-}

package/dist/types/index.d.ts

@@ -1,3 +0,0 @@
-export { parseAnatomyYAML } from "./parse.js";
-export { anatomyToTTL } from "./transform.js";
-export type { AnonymousNode, Edge, NamedNode, Node, Relation, Specification, Style, Switch, SwitchCase, } from "./types.js";

package/dist/types/parse.d.ts

@@ -1,2 +0,0 @@
-import type { Specification } from "./types.js";
-export declare function parseAnatomyYAML(raw: unknown): Specification;

package/dist/types/transform.d.ts

@@ -1,2 +0,0 @@
-import type { Specification } from "./types.js";
-export declare function anatomyToTTL(spec: Specification): string;

package/dist/types/types.d.ts

@@ -1,36 +0,0 @@
-export interface Specification {
-    root: NamedNode;
-}
-export interface NamedNode {
-    type: "named";
-    uri: string;
-    styles?: Style[];
-    edges?: Edge[];
-}
-export interface AnonymousNode {
-    type: "anonymous";
-    role: string;
-    styles?: Style[];
-    edges?: Edge[];
-}
-export type Node = NamedNode | AnonymousNode;
-export interface Edge {
-    target: Node | Switch;
-    relation: Relation;
-}
-export interface Relation {
-    cardinality: string;
-    slotName?: string;
-}
-export interface Style {
-    key: string;
-    value: string;
-}
-export interface Switch {
-    discriminator: "props" | "internal" | "override";
-    cases: SwitchCase[];
-}
-export interface SwitchCase {
-    value: string;
-    node: Node;
-}

package/dist/types.d.ts

@@ -1,36 +0,0 @@
-export interface Specification {
-    root: NamedNode;
-}
-export interface NamedNode {
-    type: "named";
-    uri: string;
-    styles?: Style[];
-    edges?: Edge[];
-}
-export interface AnonymousNode {
-    type: "anonymous";
-    role: string;
-    styles?: Style[];
-    edges?: Edge[];
-}
-export type Node = NamedNode | AnonymousNode;
-export interface Edge {
-    target: Node | Switch;
-    relation: Relation;
-}
-export interface Relation {
-    cardinality: string;
-    slotName?: string;
-}
-export interface Style {
-    key: string;
-    value: string;
-}
-export interface Switch {
-    discriminator: "props" | "internal" | "override";
-    cases: SwitchCase[];
-}
-export interface SwitchCase {
-    value: string;
-    node: Node;
-}

package/dist/types.js

@@ -1 +0,0 @@
-export {};