Specification
CorpoSpec is a convention for storing company data as plain YAML files in Git, validated by JSON Schema. The schemas are generated from a single canonical type system and published at versioned, immutable URLs.
Core concept — Company as Code
A company's structure, governance, strategy, metrics, and operations live as machine-readable files in a Git repository. Git gives you the audit log. JSON Schema gives you the contract. AI agents read, reason about, and act on company state.
This removes the split between "the company's real data" and "what tools see". Every legal entity, every decision, every hire, every forecast is a file. No CRM export. No slide deck out of date. No source of truth that nobody owns.
Design principles
SINGLE SOURCE OF TRUTH
Every fact exists in exactly one place. Never duplicate what can be referenced. If a value is computable, store only the source.
KISS
Minimal schema surface. Every field must justify its existence. If removing a field loses no information, remove it.
PATHREF BY DEFAULT
Reference entities by path — people/team/alex — never by copied attributes. A decision is its ID, not a prose summary.
VERSIONED, IMMUTABLE
Every v0.7.1 schema URL serves the same bytes forever. Consumers pin once and never break.
PathRef
A PathRef is a path relative to the .corpospec/ root, without the leading
slash and without a file extension. It identifies exactly one entity.
# In governance/decisions/0018-agent-network-architecture.md
decision_makers:
- people/team/alex
- people/team/jordan
supersedes: governance/decisions/0005-observability
Validation tools resolve PathRefs to real files at validation time. Broken references fail the build.
Pillars
Ten pillars. Every YAML file in a CorpoSpec repository belongs to exactly one. Pillar directories organise files; schemas define their shape.
Root
People
Governance
Financial
Metrics
Product
Integrations
Repository layout
A CorpoSpec repository has a single top-level directory: .corpospec/. Each pillar maps to a subdirectory.
.corpospec/ ├── manifest.yaml # root · company_id, pillars, corpospec_version ├── entity/ │ ├── company.yaml # entity │ ├── jurisdiction/de.yaml # jurisdiction-de │ └── equity/ │ ├── stakeholders/*.yaml # stakeholder │ └── stock-classes/*.yaml # stock-class ├── people/ │ ├── team/*.yaml # person │ ├── roles/*.yaml # role │ └── org.yaml # org-structure ├── governance/ │ ├── decisions/*.md # bdr │ ├── resolutions/*.yaml # resolution │ ├── strategy/okrs/*.yaml # okr │ ├── board/*.yaml # board │ └── risk/*.yaml # risk-register ├── financials/ │ ├── model.yaml # financial-model │ ├── actuals/*.yaml │ ├── forecasts/*.yaml │ └── bank-accounts/*.yaml # bank-account ├── metrics/ │ └── definitions/*.yaml # metric ├── product/ │ ├── overview.yaml # product │ ├── features/*.yaml # product-feature │ └── feature-matrix.yaml # feature-matrix ├── market/ │ ├── tam-sam-som.yaml # market-sizing │ ├── gtm-strategy.yaml # gtm-strategy │ ├── icp/*.yaml # icp │ ├── competitors/*.yaml # competitor │ ├── campaigns/*.yaml # campaign │ ├── monetization/*.yaml # monetization │ └── services-pricing.yaml # services-pricing ├── brand/ │ ├── foundation.yaml │ ├── voice.yaml │ ├── logo.yaml │ ├── colors.yaml │ ├── typography.yaml │ └── architecture.yaml ├── integrations/ │ └── sources/*.yaml # integration └── legal/ ├── contracts/agreements/*.yaml # contract ├── policies/*.yaml # policy ├── action-items/*.yaml # legal-action-item └── regulatory/*.yaml # control
Validation
CorpoSpec ships a reference validator — corpospec-validate, a Rust CLI
that generates schemas from canonical types at build time and validates every YAML
file against its pillar's schema.
Third-party validators work too, as long as they speak JSON Schema Draft 2020-12
and can resolve https://corpospec.com/schemas/<version>/*.