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.16.0 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/0042-pricing-model.md
decision_makers:
- people/team/alex
- people/team/jordan
supersedes:
- governance/decisions/0017-launch-pricing
Validation tools resolve PathRefs to real files at validation time. Broken references fail the build.
Every PathRef field declares the entity type it points to via the
x-corpospec-ref schema keyword. A field is not just "a path" —
it is a typed edge to a known kind of entity, so the whole company is a
traversable graph. The schema below says owner resolves to a
person and account to a coa entry;
a field may list several targets when the reference is polymorphic.
"owner": { "$ref": "#/$defs/PathRef", "x-corpospec-ref": ["person"] }
"account": { "$ref": "#/$defs/PathRef", "x-corpospec-ref": ["coa"] }
"counterparty": { "$ref": "#/$defs/PathRef", "x-corpospec-ref": ["vendor", "customer"] }
Two targets are reserved: self for an entity's own identity
field, and artefact for references to opaque files (a signed
PDF, a Markdown body) that are not CorpoSpec entities. The
schema explorer
derives its full relationship graph from these declarations — no edge list
is hand-maintained.
Pillars
Fourteen pillars cover every company. A fifteenth — creator — activates
when an entity declares business_type: creator_business, adding
channels, audience, content, sponsorships, and digital products. Every YAML
file in a CorpoSpec repository belongs to exactly one pillar. Pillar
directories organise files; schemas define their shape.
Root
Entity
People
Governance
Financials
Metrics
Product
Market
Brand
Integrations
Legal
Privacy
Operations
Knowledge
Repository layout
A CorpoSpec repository has a single top-level directory: .corpospec/. Each pillar maps to a subdirectory.
.corpospec/ ├── manifest.yaml # manifest · spec version, company_id, pillars ├── 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 · markdown w/ YAML frontmatter │ ├── resolutions/*.yaml # resolution │ ├── strategy/okrs/*.yaml # okr │ ├── board/members.yaml # board │ └── risk/register.yaml # risk-register ├── financials/ │ ├── model.yaml # financial-model │ ├── actuals/*.yaml # financial-model │ ├── forecasts/*.yaml # financial-model │ └── bank-accounts.yaml # bank-account ├── metrics/ │ ├── definitions/*.yaml # metric │ └── cohorts/*.yaml # cohort ├── product/ │ ├── overview.yaml # product │ ├── features/*.yaml # product-feature │ ├── feature-matrix.yaml # feature-matrix │ ├── feature-flags.yaml # product-feature-flags │ ├── lifecycle.yaml # product-lifecycle │ ├── aso.yaml # product-aso │ ├── localization.yaml # product-localization │ └── platform-config.yaml # product-platform-config ├── 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 # brand-foundation │ ├── voice.yaml # brand-voice │ ├── logo.yaml # brand-logo │ ├── colors.yaml # brand-colors │ ├── typography.yaml # brand-typography │ ├── architecture.yaml # brand-architecture │ ├── asset-catalog.yaml # brand-asset-catalog │ ├── iconography.yaml # brand-iconography │ └── photography.yaml # brand-photography ├── integrations/ │ └── sources/*.yaml # integration ├── legal/ │ ├── contracts/*.yaml # contract │ ├── policies/*.yaml # policy │ ├── action-items/*.yaml # legal-action-item │ ├── compliance/*.yaml # control · OSCAL-aligned │ └── privacy-classification.yaml # privacy-classification └── creator/ # conditional · entity.business_type = creator_business ├── channels/*.yaml # channel ├── audience-snapshots/*.yaml # audience-snapshot ├── content-series/*.yaml # content-series ├── videos/*.yaml # video ├── sponsorships/*.yaml # sponsorship ├── revenue-streams/*.yaml # revenue-stream └── digital-products/*.yaml # digital-product
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>/*.