Skip to main content

specification overview

declared-md is a family of three open standards for self-hosted public profiles.

source

the normative specification lives at github.com/declared-md/spec. in case of conflict, the source repository wins.

the three standards​

standardfilesubject
individual identitywhoami.mdpeople
organization identitywhois.mdorganizations
project identitywhatis.mdprojects

each standard is a small YAML frontmatter schema embedded in a Markdown file. the file must live in a public GitHub repository owned by the subject.

why three files​

a person, a company, and a project share zero fields by design.

  • people care about: stack, status, available_for, pronouns
  • organizations care about: size, industry, funding_stage, hiring
  • projects care about: license, status, maintained_by, language

a single schema covering all three would produce a schema bad for everyone. three focused schemas with shared philosophy work better.

shared rules​

all three standards share:

  • format: UTF-8 Markdown with valid YAML frontmatter
  • max size: 50 KB
  • required fields: declared, kind, name, handle
  • links object: all URLs must use https:// (except email which uses mailto:)
  • versioning: semantic versioning at the family level

see shared rules for the complete list.

design principle​

the file is the source of truth. the directory is just a view.

a declared-md file lives in the subject's own repository. the subject controls the data. if the directory disappears, the file remains valid. if the subject updates the file, the directory catches up on the next crawl.

version​

current version: 1.0.1

see the changelog for the history of changes.