this is a rendered mirror of the normative spec at github.com/declared-md/spec. in case of conflict, the source repository wins.
whoami.md: specification v1.0
the specification for individual identity profiles in the declared-md family.
see shared rules for encoding, file location, filename, and common validation rules that apply to all three standards.
purpose
whoami.md is a self-published identity file for individuals: developers, designers, writers, and other people who maintain a public GitHub profile.
it answers one question: who are you, in a format that is portable, machine-readable, and self-owned.
unlike a LinkedIn profile or a GitHub bio, a whoami.md file lives in the subject's own repository. the subject controls the data. any directory that indexes it is a derived view, not the source.
file location rules
| priority | location |
|---|---|
| 1 | root of <username>/<username> (profile repo) |
| 2 | root of <username>/declared repo |
| 3 | .github/whoami.md in any public repo owned by the user |
frontmatter schema
required fields
| field | type | rules |
|---|---|---|
declared | string | must be "1.0" |
kind | string | must be "whoami" |
name | string | 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 self-description. at most 120 characters. |
location | string | free-form location string. |
links | object | see links schema below. |
optional fields
| field | type | rules |
|---|---|---|
status | string | one of: open-to-work, working, building, learning, unavailable |
roles | string[] | professional roles. free-form strings. |
stack | string[] | technologies, languages, frameworks. |
focus | string[] | topics or domains currently worked on. |
languages | string[] | spoken or written languages. ISO 639-1 codes recommended. |
available_for | string[] | engagement types. examples: freelance, consulting, mentorship |
tags | string[] | free-form tags for discoverability. |
pronouns | string | free-form. |
timezone | string | IANA timezone identifier. |
links schema
| key | type | description |
|---|---|---|
github | string (URL) | GitHub profile URL. |
twitter | string (URL) | Twitter or X profile URL. |
linkedin | string (URL) | LinkedIn profile URL. |
bluesky | string (URL) | Bluesky profile URL. |
mastodon | string (URL) | Mastodon profile URL. |
site | string (URL) | personal website. |
email | string (email) | contact email, mailto: scheme. |
any additional key with an https:// value is also accepted.
body rules
- the body should be present
- there is no minimum or maximum word count
- the body should describe the person in prose
- the body must be valid Markdown
- HTML is permitted but may be stripped by directory renderers
example
---
declared: "1.0"
kind: whoami
name: Ana Ferreira
handle: ana-ferreira
headline: Full-stack developer focused on sustainable supply chain software
location: Recife, BR
status: open-to-work
roles: [software-engineer, technical-writer]
stack: [typescript, react, node, postgresql]
focus: [supply-chain, open-source, developer-tooling]
languages: [pt-BR, en]
available_for: [freelance, consulting, mentorship]
tags: [brazil, northeast, b2b]
pronouns: she/her
timezone: America/Recife
links:
github: https://github.com/ana-ferreira
site: https://anaferreira.dev
email: mailto:ana@anaferreira.dev
---
I'm a full-stack developer based in Recife, Brazil, with seven years of experience building
internal tools and APIs for logistics companies.