Spec — OrgML (Organization Markup Language)

Overview

OrgML is a compact text DSL for declaring organizational hierarchies with people, roles, vacancies, multicompany membership, and employment types. It is the canonical importexport format for `platformkompass (see kompassRFC-001`).

Design goals: humaneditable in a text editor, low verbosity, no tooling required beyond a text file and the `kompassorgml` CLI.

Reference Implementation

• *o parser:*platform/kompass/backend/internal/orgml/parser.go
• *o exporter:*platform/kompass/backend/internal/orgml/export.go
• *o converter (OrgML → Kompass entities):*platform/kompass/backend/internal/orgml/convert.go
• *LI:*platform/kompass/backend/cmd/kompass-orgml/ (import, export, validate, stats)
• *egacy JS parser:*~/dev/organograma/index.html (inline, from the legacy org chart app)

Syntax

Company Definitions

At the top of the file, before any unit card, companies (tenants) are declared:

LETTER = Name #hex

Example:

C = Crescer #10b981
K = Koder   #f59e0b
V = Vivver  #8b5cf6

• LETTER — single uppercase letter used as abbreviation in company tags ([C], [CKV])
• Name — display name of the company
• #hex — brand color in hexadecimal
• New companies can be added without changing code

Unit Card

N[Title]{#hex}

• N — integer level in the tree (1 = root, 2 = child of root, etc.)
• Title — unit name (department, section, team, etc.)
• {#hex} — card color in hexadecimal
• Hierarchy is defined by the numeric level, not by indentation
• People, vacancies, and child units belong to the last declared card at that level or higher

Example:

1[DIRETORIA]{#ef4444}
2[Gerência Administrativa]{#06b6d4}
3[LOGÍSTICA]{#06b6d4}
3[FINANCEIRO]{#06b6d4}
2[Gerência de Operações]{#f97316}

Manager (Responsável)

@ Name
@ Name [CV]
@ Name [V] (João Pessoa - PB) *Cargo*
@ Name [C] {pj}

A unit has at most one manager. The @ prefix marks the person as the unit's owner/responsible.

Member (Pessoa)

- Name
- Name [K]
- Name [V] (Cidade - UF)
- Name [C] *Cargo* {pj}

The - prefix marks a regular member of the current unit.

Owner Vacancy (Vaga de responsável)

!@ Title
!@ Title [C]
!@ Title [K] *Cargo*

An open position for the unit's manager. At most one per unit.

Member Vacancy (Vaga de pessoa)

! Title
! Title [V]
! Title [V] (Montes Claros - MG)
! Title [V] {pj} x2

An open position for a regular member. xN specifies the number of openings (default 1).

Comments

// This line is ignored by the parser

Lines starting with // are ignored.

Metadata Fields

The following metadata can appear on any person or vacancy line (@, -, !@, !):

Employment Type

If {pj} is not present, the person/vacancy is treated as CLT by default. The Kompass model supports a broader enum (clt, pj, intern, apprentice, volunteer, contract); OrgML currently maps only {pj} explicitly. Future extensions may add {intern}, {apprentice}, etc.

Mapping to Kompass Entities

Per kompass-RFC-001, OrgML maps to Kompass entities as follows:

OrgML syntax                                → Kompass entity
─────────────────────────────────────────────────────────────
C = Crescer #10b981                         → Tenant (slug=crescer, color=#10b981)
1[DIRETORIA]{#ef4444}                       → Unit (level=1, name=DIRETORIA, color=#ef4444)
2[Gerência X]{#06b6d4}                      → Unit (level=2, parent=DIRETORIA)
@ Rodrigo [CKV]                             → Person (deduped) + 3 Memberships (C, K, V)
- Gabriel [V]                               → Person + 1 Membership (Vivver)
- Cristiano [C] {pj}                        → Membership (employment_type=pj)
- Angelo [V] (João Pessoa - PB)             → Membership (location_city=João Pessoa, location_state=PB)
@ Carlos [V] *Coordenador*                  → Membership (title=Coordenador, is_manager=true)
!@ Coordenador [V]                          → Vacancy (kind=owner, quantity=1)
! Técnico [V] {pj} x3                       → Vacancy (kind=member, quantity=3, employment_type=pj)

Invariants

• *erson deduplication:*two lines with the same name produce one Person and multiple Memberships.
• *ulti-tenant membership:*[CKV] on a person creates one Membership per company.
• *nit tree per tenant:*each company gets its own copy of the unit tree (23 OrgML units × 3 companies = 69 Kompass units).
• *ound-trip:*Parse(input) → Export(chart) produces OrgML that, when parsed again, yields identical stats (people count, vacancy count, unit count).

CLI Usage

# Validate syntax
kompass-orgml validate ~/dev/organograma/OrgML.md

# Print aggregate stats
kompass-orgml stats ~/dev/organograma/OrgML.md

# Dry-run import (shows what would be inserted)
kompass-orgml import ~/dev/organograma/OrgML.md

# Apply import to database
kompass-orgml import ~/dev/organograma/OrgML.md --apply --dsn="postgres://..."

# Export tenant to OrgML (not yet implemented)
kompass-orgml export --dsn="postgres://..." --tenant=crescer

Complete Example

C = Crescer #10b981
K = Koder   #f59e0b
V = Vivver  #8b5cf6

1[DIRETORIA]{#ef4444}
@ Rodrigo Pereira de Mendonça [CKV]
2[Gerência Administrativa]{#06b6d4}
@ Fabrícia Rocha Ferro [C]
3[ADMINISTRATIVO]{#06b6d4}
- Adriana Carmelita dos Santos Medeiros [C]
- Paula Dolores das Graças Silva Mendonça [C]
! Assistente Administrativo [C] x2
2[Gerência de Operações]{#f97316}
@ Francisco Batista de Souza Neto [V]
3[DESENVOLVIMENTO]{#f97316}
- Felipe Baeta Fonseca [C]
- Cristiano Araújo da Silveira [C] {pj}
3[IMPLANTAÇÃO]{#f97316}
@ Carlos Henrique de Oliveira [V] *Coordenador de Implantação*
- Angelo Victor da Silva Albuquerque [V] (João Pessoa - PB)
- Jean Costa Pereira [V] (Pouso Alegre - MG)
3[MONITORAMENTO]{#f97316}
!@ Coordenador [V]
! Analista de BI [V]
! Analista de BI [V]
2[Gerência de Tecnologia]{#22d3ee}
@ Josmar Tonioni De Queiroz [K]
3[INFRAESTRUTURA]{#22d3ee}
- Helimar Martins Barbosa [C]

Compatibility

The Go parser supports only the current OrgML syntax. The legacy JS parser in the org chart app (~/dev/organograma/index.html) additionally accepts:

• Markdown headings (#, ##, ###) as unit cards
• Verbose intermediate format (card "Title" color=..., owner "Name" ..., person "Name" ...)

These legacy formats are not part of the canonical spec and should not be used in new files.