source

this is a rendered mirror of the normative spec at github.com/declared-md/spec. in case of conflict, the source repository wins.

shared rules

this document defines the rules that apply to all three standards in the declared-md family: whoami.md, whois.md, and whatis.md.

---

encoding and format

all declared-md files must be:

• UTF-8 encoded
• valid Markdown with valid YAML frontmatter
• at most 50 KB in total file size

---

file locations

a declared-md file must live in one of the following three locations in a public GitHub repository:

priority	location	description
1	root of the canonical repo	see per-standard rules for what "canonical" means
2	root of a repo named declared	any public repo the subject owns or controls
3	.github/<filename>	inside the .github directory of any public repo

when a subject publishes the same standard in multiple valid locations, the indexer uses priority order: location 1 wins over location 2, location 2 wins over location 3.

the repository must be hosted on github.com, accessible without authentication, and owned by the same user or organization as the declared subject.

---

filename rules

each standard has exactly one canonical filename. no aliases, no capitalization variants, no .yaml extensions.

standard	canonical filename
individual identity	whoami.md
organization identity	whois.md
project identity	whatis.md

a file named WHOAMI.md, WhoAmI.md, or whoami.yaml must not be accepted by the validator or indexer.

---

required frontmatter fields

all three standards share the following required fields:

field	type	description
declared	string	spec version. must be "1.0" for this version.
kind	string	identifies which standard this file implements.
name	string	display name of the subject. must be at least 1 character.
handle	string	URL slug for the subject. see handle rules below.

the declared field

the declared field declares which version of the spec the file targets. the value must be a string: "1.0". note the quotes. an unquoted 1.0 is a float in YAML and must be rejected.

the kind field

file	required value
whoami.md	whoami
whois.md	whois
whatis.md	whatis

a whoami.md file with kind: whois in its frontmatter must fail validation.

the handle field

the handle field must:

• match the regular expression ^[a-z0-9-]{2,39}$
• be lowercase only
• contain only alphanumeric characters and hyphens
• be at least 2 characters long
• be at most 39 characters long
• not start or end with a hyphen

examples of valid handles: treblavg, declared-md, my-project.

examples of invalid handles: T, my_project, -starts-with-hyphen, ends-with-hyphen-.

---

links object

all three standards use a links object for external URLs:

• the links object accepts any key (the set of keys is not closed)
• all values must use the https:// scheme, except email which uses mailto:
• plain http:// URLs must be rejected

---

common validation rules

the validator must enforce the following for every declared-md file:

1. the file is valid UTF-8
2. the frontmatter parses as valid YAML
3. all four required fields are present: declared, kind, name, handle
4. the declared value is a known spec version string
5. the kind value matches the standard for the filename being validated
6. the handle value matches ^[a-z0-9-]{2,39}$
7. the total file size is at most 50 KB
8. all URLs in links use the https:// scheme

failures in any of these rules must result in the file being marked invalid.

---

versioning policy

the declared-md spec follows semantic versioning at the family level.

• patch releases (1.0.x): corrections to wording, no schema changes
• minor releases (1.x.0): new optional fields, backward-compatible
• major releases (x.0.0): breaking changes to required fields or validation rules

a file that is valid against v1.0 must remain valid in any v1.x release.

---