Org chart

About org charts

An org chart (organizational chart) maps the formal reporting structure of an organization — who manages whom, which teams sit under which leaders, and where open roles and external advisors fit in. HR teams reach for them during headcount planning; founders use them before board meetings; operations managers circulate them when restructuring. Unlike a generic flowchart, an org chart treats people (and positions) as the primary entities, with the hierarchy encoded by indentation or explicit edges.

Schematex follows general org-chart conventions with extensions for open/unfilled positions, matrix (dotted-line) reporting, and assistant relationships. There is no single ISO standard for org charts; the conventions implemented here are drawn from HR practice and software-industry norms. For the authoritative academic background see Fayol (1916) and the Wikipedia article on org charts.

1. Your first org chart

The smallest useful org chart: a three-level hierarchy with one open role.

Four rules cover 80% of usage:

1. Start with the keyword orgchart, optionally followed by a quoted title.
2. Each person is a node — id: "Name" | "Title" | "Department" [props]. The | separates the name, title, and department fields.
3. Indentation determines hierarchy — each extra two (or more) spaces moves a node one level deeper under the nearest less-indented node above it.
4. Declare open roles with open id: or draft id:, and external advisors with advisor id:.

Comments must start with # on their own line (inline trailing // is also stripped).

2. Nodes

A node line has the form [kind] id: fields [props]. The id must match [A-Za-z][A-Za-z0-9_-]*.

2.1 Fields (pipe-separated)

The part after the : and before the optional [props] block is split on |:

alice: "Alice Zhang"                                # name only
alice: "Alice Zhang" | "VP Engineering"             # name + title
alice: "Alice Zhang" | "VP Eng" | "Platform"        # name + title + department
alice: "Alice Zhang" | "VP Eng" | "Platform" | "x@co.com"  # + info line

2.2 Node kinds

The optional kind keyword before the id changes how the node is rendered:

2.3 Node properties

Properties go in [key: value, …] at the end of a node line.

Role icons — the role: value resolves to a display icon. Accepted keywords (case-insensitive):

3. Hierarchy

Hierarchy is expressed by indentation — the most common pattern. Each node becomes a child of the nearest node above it that has a smaller indent. Tabs are treated as two spaces.

ceo: "CEO"
  cto: "CTO"           # child of ceo (indent 2)
    eng: "Engineer"    # child of cto (indent 4)
  cfo: "CFO"           # child of ceo (indent 2, same level as cto)

Alternatively, use the reports: property to set a parent explicitly regardless of indentation:

orgchart "Flat file"
ceo: "CEO"
cto: "CTO" [reports: ceo]
eng: "Engineer" [reports: cto]

4. Edges

Two kinds of edges exist. Most reporting lines come from the indentation hierarchy automatically. You can also write them explicitly — or add matrix (dotted) lines.

Explicit edges require that both node ids are already declared. A report edge created explicitly is not duplicated if the same relationship is already implied by indentation.

Edge labels are supported:

pm1 -.-> design [label: "product partnership"]

5. Configuration

config: lines adjust layout and orientation. Each goes on its own line.

Layout notes:

• tree — standard hierarchical tree with branching connectors. Best for most org charts.
• list / directory / compact — compact indented directory view. Good for large headcount lists where tree branching becomes unwieldy.

Tree layout (default) — avatar cards with branching connectors and department color-coding. Best for teams up to ~30 people.

List layout — compact directory rows with indent guides. Best for large teams where tree branching becomes unwieldy.

6. Labels & comments

• Title: orgchart "Acme Corp" — first line only.
• Name field: first pipe-delimited field after the colon; may be quoted ("Alice Zhang") or unquoted (Alice).
• Title/department fields: second and third pipe-delimited fields.
• Info line: fourth pipe-delimited field, or set via note:, email:, phone:, or location: props. First one encountered wins.
• Comments: # at the start of a line (after leading whitespace). Inline // is also stripped.

7. Reserved words & escaping

Reserved at line start: orgchart (header), config:, role, open, draft, tbh, advisor, external.

Reserved operator tokens — avoid these sequences inside ids: ->, -.->

ID rules: must match [A-Za-z][A-Za-z0-9_-]*. Names with spaces go in the quoted name field, not the id.

Strings with spaces in props values (e.g. department: "Platform Eng") must be double-quoted.

8. Common mistakes

9. Grammar (EBNF)

document       = header (blank | comment | config | edge | node)*

header         = "orgchart" ( WS quoted-string )? NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

config         = "config" WS ":" WS key WS "=" WS value NEWLINE
key            = "direction" | "layout"

node           = INDENT* kind? id ":" WS fields ( "[" node-attrs "]" )? NEWLINE
kind           = "role" | "open" | "draft" | "tbh" | "advisor" | "external" | "person"
fields         = field ( "|" field )*
field          = quoted-string | unquoted-text
node-attrs     = node-attr ("," node-attr)*
node-attr      = "role:" role-keyword
               | "icon:" role-keyword
               | "department:" text
               | "status:" ( "new" | "leaving" | "on-leave" )
               | "avatar-color:" quoted-hex
               | "gender:" ( "male" | "female" )
               | "note:" text
               | "email:" text
               | "phone:" text
               | "location:" text
               | "assistant-of:" id
               | "matrix:" id-list
               | "reports:" id
               | bare-flag

bare-flag      = "open" | "draft" | "tbh" | "external"

edge           = id WS edge-op WS id ( "[" edge-attrs "]" )? NEWLINE
edge-op        = "->" | ".->"  // -.-> for matrix
edge-attrs     = "label:" quoted-string

id             = [A-Za-z] [A-Za-z0-9_-]*
comment        = ( "#" | "//" ) any NEWLINE

Authoritative source: src/diagrams/orgchart/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

10. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• assistant-of: visual rendering — the property is parsed and stored in the AST but the renderer does not yet draw the assistant elbow connector.
• Config coloring — department-based color themes (coloring: department).
• Config compact size tiers — explicit card-size control (size: small | medium | large).
• span: node width — spanning a node across multiple sibling columns in tree layout.
• Photo / avatar URL — avatar: "https://…" to display a real headshot.
• Export to HRIS formats — JSON/CSV structured output alongside the SVG.

Track in the GitHub issues if you need any of these sooner.