YAML specs
The same diagrams as data files, for generated or non-Python workflows.
Every Python feature has a YAML form. YAML suits diagrams generated by other tools, or teams that prefer data files; Python is easier for anything with repetition. Both load into the same model and render identically.
# The same diagram as quickstart.py. No coordinates: spinagram sizes and places everything.
# spinagram render examples/quickstart.yaml -f svg,png,pptx -o out/
id: Q01
title: Web app on AWS
subtitle: No coordinates, laid out automatically
groups:
- id: region
label: us-east-1
style: aws-region
direction: right
children:
- id: vpc
label: VPC
style: aws-vpc
direction: right
children: [lb, api, data]
- s3
- {id: data, children: [db, cache]}
nodes:
- {id: users, title: Users, icon: "aws:users"}
- {id: lb, title: Load balancer, icon: "aws:alb"}
- {id: api, title: API, text: FastAPI on ECS, icon: "terrastruct:python"}
- {id: db, title: Orders DB, text: PostgreSQL, icon: "terrastruct:postgres"}
- {id: cache, title: Cache, text: Redis, icon: "terrastruct:redis"}
- {id: s3, title: Uploads, text: S3 bucket, icon: "aws:s3"}
edges:
- "users -> lb: HTTPS"
- lb -> api
- "api -> db: SQL"
- api -> cache
- api -> s3
spinagram render examples/quickstart.yaml -f svg,png,pptx -o out/Structure
| Key | Meaning |
|---|---|
id, title | Required. The id names files and orders slides |
subtitle, source, kicker | Page chrome text |
layout | Engine and direction for automatic layout: {engine: elk, direction: down} |
groups | Nested containers: {id, label, style, direction, children: [...]} |
nodes | {id, title, text, icon, style, kind, x, y, w, h}; at: [x, y, w, h] is a shorthand |
edges | Shorthand strings or {from, to, label, color, dashed, via, arrow} |
zones, tables, legend | Fixed-position extras, see Manual layout |
facts, locale | Facts file and number format |
category, tags | Catalog metadata for serve and --tag/--category, see Python guide |
Edge shorthand
"<from> -> <to>[: label]", where an endpoint is a node id (the facing side is picked
automatically) or node.side[@frac] with side one of top|bottom|left|right|center and frac a
position from 0 to 1 along that side. <-, <-> and -- (no arrow) work too.
Folder defaults
A _defaults.yaml next to the specs supplies keys every diagram in that folder shares, such as
facts, locale or layout. A folder category applies to diagrams without one, and folder tags
are added to every diagram's tags. Files starting with _ are not loaded as diagrams.
From Python to YAML
spinagram layout spec.py -o spec.yaml writes any diagram, Python or YAML, as an explicit YAML spec
with its computed positions.