yaml-reference.md

YAML Reference

This is a compact reference for the full Spytial YAML specification. For detailed explanations and examples, see the Constraints and Directives guides.

Generating specs from a host language? Read the machine-readable contract instead of this page — it ships with every release, carries its own version, and is tested against the engine parser:

https://cdn.jsdelivr.net/gh/sidprasad/spytial-core@<tag>/docs/spytial-language.json
https://cdn.jsdelivr.net/gh/sidprasad/spytial-core@<tag>/docs/spytial-spec.schema.json

Structure

constraints:
  - # ... constraint definitions

directives:
  - # ... directive definitions

Both sections are optional. An empty specification is valid.

Each section must be a list of single-key entries. The parser ignores anything it does not recognize — an unknown directive, a misspelled field, or a section written as a mapping instead of a list all pass silently and then do nothing. Validate against spytial-spec.schema.json if you want a typo to be an error.

Every block-bodied item also accepts an optional source: { text, location? } block — the rule as its author wrote it in the surface that generated the spec. Conflict reports cite that text instead of Spytial's own rendering. See author provenance.

---

Constraints at a Glance

Constraint	Purpose	Required Fields
orientation	Position elements relative to each other	selector, directions
cyclic	Arrange elements in a circle	selector
align	Align elements on an axis	selector, direction
hold: never	Negate any constraint	Add hold: never to any constraint
group	Group elements visually	selector, name
size	Set node dimensions	width, height
hideAtom	Remove atoms from view	selector

---

Directives at a Glance

Directive	Purpose	Required Fields
atomStyle	Style nodes (fill, border, icon, label)	— (no selector = every atom)
edgeStyle	Style edges (line, label)	field
attribute	Show edge data as node labels	field
tag	Add computed labels to nodes	toTag, name, value
hideField	Hide edges for a relation	field
inferredEdge	Create edges from computed selectors	name, selector
flag	Global display flags	flag value

size and hideAtom are constraints — they change what the layout has to place, not how a solved layout looks. Writing them here still parses, identically, but is deprecated and warns.

Deprecated, still parsed: icon → atomStyle.iconStyle, atomColor → atomStyle.borderStyle, edgeColor → edgeStyle.lineStyle. Each raises a deprecation warning on the parsed spec.

Removed: group's field/groupOn/addToGroup. Write a binary selector instead — its first column is the group key, its second the members. This one is a parse error, not a warning.

projection is not a directive — it is a pre-layout data transformation. A projection: entry in a spec is silently ignored.

---

Selector Quick Reference

Selectors use Forge relational syntax. AlaSQL is also supported as an alternative. See the full Selector Syntax guide.

Unary selectors return a set of atoms — used by atomStyle, align, hideAtom, group, size:

selector: Node                        # All Node atoms
selector: "Node - left.Node"          # Leaf nodes (no left child)

Binary selectors return pairs of atoms — used by orientation, cyclic, inferredEdge:

selector: left                        # The left relation
selector: "^(left + right)"           # All descendants

---

Complete Skeleton

constraints:
  # Structural layout
  - orientation:
      selector: parent
      directions: [above]

  - align:
      selector: siblings
      direction: horizontal

  - group:
      selector: Team.members
      name: "Team"

  - cyclic:
      selector: nextState
      direction: clockwise

  - orientation:
      selector: siblings
      directions: [above]
      hold: never

  # Geometry and visibility are structural too
  - size:
      selector: ImportantNode
      width: 150
      height: 80

  - hideAtom:
      selector: HelperNode

directives:
  # Visual styling
  - atomStyle:
      selector: Person
      borderStyle: { color: "#4a90d9" }

  - edgeStyle:
      field: error
      lineStyle: { color: red, pattern: dashed }

  - attribute:
      field: age
      selector: Person
      textStyle: { size: large, color: "#c0392b" }  # optional: shared size + color block

  - tag:
      toTag: Student
      name: grade
      value: currentGrade
      textStyle: { size: small, color: "#2980b9" }

  - atomStyle:
      selector: File
      iconStyle:
        path: "file-icon"
        placement: badge

  - hideField:
      field: internal

  - inferredEdge:
      name: "ancestor"
      selector: "^parent"
      lineStyle: { color: gray, pattern: dotted }

  - flag: hideDisconnectedBuiltIns