PURPOSE.yml reference

PURPOSE.yml is optional, and the normal case is not to have one. A repository without it is fully and equally adopted, with every default below applied.

What the registry reads, and when

The registry reads PURPOSE.yml from the root of the default branch when a claim on the repository completes, when a steward asks for it to be read again, and once a week. It checks the file against the published format — purpose-yml.v1.json in the specification repository — and keeps one record for each version of the file it has seen.

Nothing it reads is shown or applied yet. The display metadata, the comparison with the licence and the list of rejected fields are recorded, and not shown in the project’s registry record yet. Category defaults are recorded only: routing takes nothing from the file. The attribution section is checked and not kept: the registry records only whether it was accepted and a fingerprint of it, never the paths, accounts or shares it names, and attribution takes nothing from it yet.

The licence and registry remain authoritative

PURPOSE.yml carries operational content only. Any field in it that looks like a legal designation — a licence id or URL, a licensor — is an informational mirror: non-authoritative. The LICENSE file governs.

Legal roles are verified through the registry or fixed in the licence itself. Repository metadata is useful for tooling, but changing it cannot grant those roles.

Where it goes

Repository root, next to LICENSE:

LICENSE          the canonical licence text — the whole of adoption
PURPOSE.yml      optional operational metadata — this file

A complete, annotated example

Only schema is required. This example shows every other field at once, which no real repository would need:

# PURPOSE.yml — operational metadata only. The LICENSE file governs.
# Informational mirrors (license, licensor) are NON-AUTHORITATIVE.
schema: 1                           # required; 1 is the only published version

# --- Informational mirrors. Convenience for tooling; never a designation. ----------
license:
  id: PurposeSource-1.0             # must match the licence detected in LICENSE
  url: https://purposesource.org/license
licensor:
  name: Example Maintainers
  url: https://example.invalid/maintainers

# --- Display metadata. Cosmetic: no gate, price or allocation reads it. ------------
display:
  name: purpose-cli                 # default: the repository name
  summary: A command-line client for the public registry.
  homepage: https://example.invalid/purpose-cli
  docs: https://example.invalid/purpose-cli/docs
  contact: https://example.invalid/purpose-cli/contact   # a handle or URL, never a personal address
  topics: [cli, tooling]            # up to 12 lowercase slugs

# --- Successor designation. Recorded and displayed; legally inert. ----------------
successor: ''                       # empty: no designation

# --- Category defaults. Advisory; slugs from the seven published categories. -------
allocation:
  defaults: [education, research, health]

# --- Attribution overrides. Bounded; one invalid field rejects the whole section. --
attribution:
  exclude_paths:                    # files given weight 0: generated or vendored code
    - vendor/**
    - '**/*.generated.ts'
  exclude_users:                    # accounts whose contributions are never attributed
    - release-bot
  weights:                          # re-class a path; the class fixes its weight
    - { path: 'docs/**', class: docs }
  manual_splits:                    # contributors outside git, at most 20% in total
    - { login: example-designer, node_id: U_kgDOEXAMPLE1, micro_shares: 50000 }
  ignore_revs_extra:                # commits skipped alongside .git-blame-ignore-revs
    - 0123456789abcdef0123456789abcdef01234567

Field reference

Field	Default when absent	What the registry does with it	Authoritative?
schema	— (required)	Parser selection. Any version other than 1 means the whole file is ignored and every default applies	—
license.id	Read from LICENSE	Compared with the licence detected in LICENSE. A mismatch is recorded, is not shown in the registry record yet, and changes no legal fact	No — mirror
license.url	none	Recorded. Nothing reads it: the canonical text at the steward’s endpoint governs	No — mirror
licensor.name, licensor.url	none	Recorded. Nothing reads it: it grants nothing and assigns nothing	No — mirror
display.name	Repository name	Recorded, not shown yet. The display name for the project’s registry record	Yes, for display
display.summary	Repository description	Recorded, not shown yet. The one-line summary for the project’s registry record and the registry index, up to 300 characters	Yes, for display
display.homepage	none	Recorded, not shown yet. The homepage link for the project’s registry record, when it is an http or https address	Yes, for display
display.docs	none	Recorded, not published: the registry record has no field for it yet	Yes, for display
display.contact	none	Recorded, not published: the registry record has no field for it yet. Never a personal email address: the file itself is public	Yes, for display
display.topics	Repository topics	Recorded, not shown yet. Up to 12 topic slugs for the project’s registry record and the registry index	Yes, for display
successor	none	A successor designation, recorded and not displayed yet; legally inert until the succession process is settled	No — recorded only
allocation.defaults	none	Recorded only. Slugs from the seven published categories. Routing does not read them: the pool follows the categories chosen on the project dashboard, and otherwise the board’s allocation key	Advisory only
attribution.exclude_paths	none	Checked, not kept, not applied yet. Up to 100 globs whose files get weight 0	Yes, within the algorithm’s rules
attribution.exclude_users	none	Checked, not kept, not applied yet. Up to 50 GitHub logins left out of attribution	Yes, within the algorithm’s rules
attribution.weights	none	Checked, not kept, not applied yet. A path re-classed as code (1.0), docs (0.3) or excluded (0) — a class, never a number	Yes, within the algorithm’s rules
attribution.manual_splits	none	Checked, not kept, not applied yet. Up to 10 shares for contributors who work outside git, at most 20% of the repository in total	Yes, within the algorithm’s rules
attribution.ignore_revs_extra	none	Checked, not kept, not applied yet. Up to 500 further commits skipped, alongside the repository’s .git-blame-ignore-revs	Yes, within the algorithm’s rules

There is no weight-class field. A repository’s weight class is requested on the project dashboard and decided by the steward (weight class).

Rules

1. No legal designation. Restated because it is the whole point: the steward organisation is a licence constant, the Project Steward is whoever holds administrative control (and can be re-designated only through the registry’s verified claim flow), and steward succession is a clause in the licence. None of the three can be set here.
2. No prices, bands, or terms. Prices live in one published schedule for everyone (Art. 11). A manifest that tried to set a price would be ignored, and the attempt is worth reporting.
3. No weight class. The file has no weight field, so no file can request or grant a class.
4. No free-text cause recipients. allocation.defaults selects among the seven published categories only, and an unknown slug is rejected. The choices routing follows are made on the project dashboard, not in this file.
5. Category defaults are advisory and recorded only. Routing does not read them; it follows the categories chosen on the project dashboard, and otherwise the board’s allocation key. The Association keeps final discretion over distribution among the categories — which is both a governance choice and a requirement of the tax framework for a Swiss entity routing funds abroad.
6. Attribution overrides are bounded. You can exclude paths and accounts, re-class a path, and give contributors who work outside git up to 20% of the repository in total, which scales the computed shares down to make room. You cannot invent a weight, and a split must name a real GitHub account that is not excluded.
7. Invalid is rejected, never guessed. A file that cannot be parsed, is larger than 64 KiB, or names a schema version other than 1 is ignored in whole: the registry records the refusal, and the last version of the file it accepted stays the current one — or none does, and the defaults apply. Outside attribution, an invalid or unknown field is rejected on its own: its default applies and the rest of the file stands. Inside attribution, one invalid field rejects the whole section, never part of it. Each rejection is recorded by field and reason; the registry record does not show that list yet.
8. Deleting the file restores the defaults. When the weekly read, a completed claim or a steward’s read finds no PURPOSE.yml, the registry holds no version of it as current any more, and every default applies.

What a manifest is not

• Not required. Not a registration. Not an account.
• Not read by the licence. The licence text mentions no repository file at all.
• Not a claim. Committing a manifest proves nothing about who you are; administrative control is proved through the claim flow.
• Not a channel for terms addressed to administrators. Those live in the claim terms, and only there.

Related

• Adoption guide — the one file that actually matters
• Leaving — deleting the manifest changes no legal position
• Algorithms and schedule versions — the attribution and routing rules these fields feed
• Waivers — how a free, public exception works