Class spec

A class diagram is UML: classes drawn as boxes with attribute and method compartments, joined by typed relations. It suits domain models, type hierarchies and interface implementations. A spec is one JSON object with "type": "class".

class.json

{
  "type": "class",
  "direction": "DOWN",
  "theme": "default",
  "classes": [
    {
      "id": "order",
      "label": "Order",
      "stereotype": "entity",
      "type_params": ["T"],
      "color": "blue",
      "attributes": [{"visibility": "-", "text": "id: string"}],
      "methods": [{"visibility": "+", "text": "total(): Money", "static": false, "abstract": false}]
    },
    {"id": "item", "label": "Item"}
  ],
  "relations": [
    {
      "id": "r1",
      "from": "order",
      "to": "item",
      "kind": "composition",
      "label": "contains",
      "from_card": "1",
      "to_card": "*",
      "color": "red"
    }
  ],
  "packages": [{"id": "domain", "label": "Domain", "contains": ["order", "item"], "color": "gray"}],
  "legend": true,
  "legend_labels": {"inheritance": "is-a"},
  "ignore": ["god-class"]
}

For how to draw well with it, see the Class diagrams guide.

A key diago does not know is ignored and reported by check as unknown-field. No id may hold a control character, U+FFFE or U+FFFF. Every text field is drawn on one line: a newline or other control character in it prints as its escape (\n). A spec that breaks a rule below is a validation error on the field’s path, such as relations[0].kind, and exits 1.

Top level

Field	Type	Default	Allowed values	Notes
type	string	required	class
title	string	none	any text	A band above the diagram in SVG and PNG, a centered first line in text art. Never part of the layout.
theme	string	default	default, dark, midnight, sketch, or a theme file in DIAGO_THEME_DIR	The theme the render uses unless -theme overrides it. Text art takes none. A name that does not load is a validation error on theme.
direction	string	DOWN	DOWN, UP, RIGHT, LEFT, AUTO	Upper case only. Unlike a flow spec, an absent direction means DOWN.
classes	array of class	required	at least one
relations	array of relation	none
packages	array of package	none		Groups of classes: the flow group rules under another key.
legend	boolean	false	true, false	true adds one row per relation kind present in the diagram.
legend_labels	object	none	keys are relation kinds	Overrides a legend row’s text. An empty value hides the row. A key that is not a relation kind is a validation error.
ignore	array of string	none	an advisory rule name each	Silences those rules for this spec. An unknown name is a validation error. See Advisories.

legend_labels on its own, without legend, draws nothing: it is checked, but only legend: true adds the legend. A top-level style key was removed and is reported as removed-field.

Class

Field	Type	Default	Allowed values	Notes
id	string	required		Unique, not empty. Relations and packages refer to it. It must not contain -> or end in @ and digits (such as db@2): derived edge ids and layout anchoring use those forms.
label	string	the id		The class name.
stereotype	string	none	any text	Drawn as «stereotype» above the name.
type_params	array of string	none	non-empty strings	Generic parameters, drawn after the name inside angle brackets.
color	string	the theme’s	red, green, blue, yellow, orange, purple, gray, or #rrggbb
attributes	array of member	none		The attributes compartment.
methods	array of member	none		The methods compartment.

Member

An attribute or a method line.

Field	Type	Default	Allowed values	Notes
text	string	required		The member as written, such as id: string or total(): Money. Not empty.
visibility	string	none	+, -, #, ~	Drawn before the text.
static	boolean	false	true, false	Underlines the member. In text art, a $ suffix.
abstract	boolean	false	true, false	Italicises the member. In text art, a * suffix.

Relation

Field	Type	Default	Allowed values	Notes
id	string	from->to#n		As for flow edges: stable across edits, and derived from from and to as written. When present it must not be empty or repeat another relation’s id.
from	string	required	a class id
to	string	required	a class id
kind	string	association	association, inheritance, realization, dependency, aggregation, composition	For inheritance and realization, from is the subtype and to the supertype or interface; the supertype is laid out first and the hollow triangle is drawn at its end. A class cannot inherit from or realize itself.
label	string	none		Drawn beside the relation.
from_card	string	none	any text, such as 1 or 0..*	Cardinality beside the from end.
to_card	string	none	any text	Cardinality beside the to end.
directed	boolean	true for dependency, else false	true, false	An arrowhead at to. Not allowed on the four adorned kinds, inheritance, realization, aggregation and composition, whose own end marker replaces it: giving directed on one is a validation error.
color	string	the theme’s	red, green, blue, yellow, orange, purple, gray, or #rrggbb

Give every relation an explicit id: one without it is reported as edge-without-id under render -previous and diff.

Package

A package is a group under another key: the same fields as a flow group.

Field	Type	Default	Allowed values	Notes
id	string	required		Unique among packages, and not the id of a class. It must not contain -> or end in @ and digits (such as db@2): derived edge ids and layout anchoring use those forms.
label	string	required		Drawn on the frame.
contains	array of string	none	class ids and package ids	A package id makes a child package. A class or package belongs to at most one. Up to 3 levels. A package with nothing in it is reported as empty-group.
color	string	the theme’s	red, green, blue, yellow, orange, purple, gray, or #rrggbb

Output notes

SVG draws each relation kind with its own end marker, and the wire stops at the marker. Text art uses the glyphs △, ▽, ◁, ▷, ◆ and ◇. draw.io and Excalidraw export cover flow diagrams only.

Using the schema in an editor

The JSON schema for class specs is served at /schemas/class.json. Map it to your spec files in your editor’s JSON settings to get completion and the allowed values of every enum. Do not put a "$schema" key in the spec itself: diago reports it as unknown-field (unknown key "$schema" is ignored), so the editor’s own schema mapping is the way.