Skip to main content

frequently asked questions

why three files instead of one?

a person, a company, and a project share zero fields by design. people care about stack, status, available_for, pronouns. companies 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 that is bad for everyone. three focused schemas with shared philosophy work better.

how is this different from uses.tech?

uses.tech is a directory of developer hardware and software setups (/uses pages). declared-md is a family of schemas for public identity files -- who you are, what your org does, what your project is. different subjects, different fields, different purpose.

how is this different from llms.txt?

llms.txt is a convention for providing LLM-friendly context about a website at a specific URL. declared-md files are structured identity profiles with typed frontmatter schemas, indexed into public directories. the use cases overlap only in that both are files in a repo. the fields and audiences are different.

what if I don't want to be indexed?

don't publish the file, or don't publish it at a canonical location. the indexer only processes files at the three canonical paths. files at any other path are silently skipped.

a private: true flag is planned for a future version. for now, absence of the file is the only opt-out.

how do you prevent fake profiles?

v1.0 uses GitHub repo ownership as identity proof. if you control the repo, you can publish the file. the indexer does not verify identity claims beyond that.

stronger verification (domain ownership, cryptographic signatures) is a v2 question. for now, the indexer surfaces the source repo URL with every profile so viewers can verify ownership themselves.

why GitHub only?

GitHub is where the initial audience of developers, open-source projects, and tech organizations already has a public presence. v1.0 scopes to GitHub to keep the implementation simple and the spec focused.

GitLab and Codeberg support are planned for a future version.

will it stay free?

the spec, CLI, indexer, and directory are all MIT licensed and will remain free. the infrastructure runs on GitHub's free tier (GitHub Actions, GitHub Pages).

if hosted features come later (e.g., verified identity, analytics), those may be paid. the core open standard stays open.

can I use it for non-developer profiles?

yes, with caveats. the file location rules require a public GitHub repository, which implies at minimum a GitHub account. the fields skew toward technical subjects. non-technical users without a GitHub presence can't currently participate.

future versions may support profiles hosted outside GitHub, but v1.0 is GitHub-only by design.

can a single person have multiple whoami.md files?

no. one file per subject per kind. a person publishes one whoami.md. if files exist at multiple canonical locations, the indexer deduplicates and keeps only the highest-priority one. publishing in multiple locations is not harmful -- the extra files are silently ignored.

how long until my profile appears after publishing?

after publishing to a canonical location:

  1. the GitHub Search API indexes the file -- this can take minutes to hours
  2. the declared-md indexer must run -- check the Actions tab in declared-md/index
  3. the directory site must rebuild -- triggered by the indexer or by the next push to main

total latency: typically under 24 hours. check troubleshooting if your profile doesn't appear.