source
this is a rendered mirror of the normative spec at github.com/declared-md/spec. in case of conflict, the source repository wins.
whois.md: specification v1.0
the specification for organization identity profiles in the declared-md family.
see shared rules for encoding, file location, filename, and common validation rules.
purpose
whois.md is a self-published identity file for organizations: companies, nonprofits, open-source collectives, and other institutional subjects that maintain a public GitHub presence.
file location rules
| priority | location |
|---|---|
| 1 | root of the org's primary public repository |
| 2 | root of <org>/declared repo |
| 3 | .github/whois.md in any public repo owned by the org |
frontmatter schema
required fields
| field | type | rules |
|---|---|---|
declared | string | must be "1.0" |
kind | string | must be "whois" |
name | string | legal or display name. at least 1 character. |
handle | string | URL slug. must match ^[a-z0-9-]{2,39}$. |
recommended fields
| field | type | rules |
|---|---|---|
headline | string | one-line description. at most 120 characters. |
kind_of_org | string | one of: company, nonprofit, community, collective, gov, educational |
headquarters | string | free-form location. |
links | object | see links schema. at least site or github must be present. |
optional fields
| field | type | rules |
|---|---|---|
founded | string | four-digit year, e.g. "2022" |
size | string | one of: solo, 2-10, 11-50, 51-200, 201-500, 501-1000, 1000+ |
industry | string[] | industry tags. free-form strings. |
stack | string[] | publicly known technology stack. |
hiring | boolean | true or false |
remote_policy | string | one of: remote-first, hybrid, office-first, office-only |
funding_stage | string | one of: bootstrapped, pre-seed, seed, series-a, series-b-plus, public, acquired |
tags | string[] | free-form tags. |
links schema
| key | type | description |
|---|---|---|
site | string (URL) | organization website. |
github | string (URL) | GitHub organization URL. |
twitter | string (URL) | Twitter or X profile URL. |
linkedin | string (URL) | LinkedIn company page URL. |
careers | string (URL) | jobs or careers page URL. |
when links is present, at least one of site or github must be present. any additional key with an https:// value is also accepted.
example
---
declared: "1.0"
kind: whois
name: Acme Robotics
handle: acme-robotics
headline: Industrial robotics for small manufacturers in Latin America
kind_of_org: company
headquarters: Curitiba, BR
founded: "2022"
size: 11-50
industry: [robotics, manufacturing, hardware]
stack: [rust, python, ros]
hiring: true
remote_policy: hybrid
funding_stage: seed
tags: [latam, b2b, hardware]
links:
site: https://acme-robotics.com
github: https://github.com/acme-robotics
careers: https://acme-robotics.com/jobs
---
Acme Robotics builds affordable robotic arms for small and mid-size manufacturers in Latin America.