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.

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

Every field is optional. This example shows all of them at once, which no real repository would need:

# PURPOSE.yml — operational metadata only. The LICENSE file governs.
# Informational mirrors (license, steward, registry) are NON-AUTHORITATIVE.
schemaVersion: 1

# --- Informational mirrors. Convenience for tooling; never a designation. ----------
license: PurposeSource-1.0-draft   # mirror of the LICENSE text's own version
steward: Purpose Source Association # mirror; the licence text names the steward
registry: https://purposesource.org/registry

# --- Display metadata. Affects the registry listing, nothing else. ----------------
display:
  name: purpose-cli                 # default: the repository name
  summary: >-                       # default: the repository description
    A command-line client for the public registry.
  homepage: https://example.invalid/purpose-cli
  tags: [cli, tooling]              # facets on the registry browse page

# --- Cause categories. Advisory. Art. 7 of the statutes keeps final discretion. ----
causes:
  # Must sum to 100. Categories are the seven published ones, no free text.
  education: 50
  research: 30
  health: 20

# --- Weight class. A REQUEST, reviewed; never self-granted. -----------------------
weight:
  requested: infrastructure         # library | application | infrastructure
  rationale: >-
    Depended on by other registered projects as a build-time dependency.

# --- Attribution overrides. Operational, and bounded by the published algorithm. ---
attribution:
  exclude_paths:                    # generated or vendored code, excluded from Impact Shares
    - vendor/**
    - '**/*.generated.ts'
  bot_identities:                   # accounts whose commits are never attributed
    - dependabot[bot]
    - renovate[bot]

# --- Contact for waiver requests. A published address, not a person. --------------
contact:
  waivers: opensource@example.invalid

Field reference

Field	Default when absent	What it affects	Authoritative?
`schemaVersion`	`1`	Parser selection. An unknown version is ignored with a warning, never guessed at	—
`license`	Read from `LICENSE`	Nothing. Tooling convenience	No — mirror
`steward`	The licence text’s constant	Nothing	No — mirror
`registry`	The licence text’s constant	Nothing	No — mirror
`display.name`	Repository name	The registry listing’s title	Yes, for display
`display.summary`	Repository description	The listing’s one-line summary	Yes, for display
`display.homepage`	Repository homepage	A link on the listing	Yes, for display
`display.tags`	none	Facets on registry browse	Yes, for display
`causes`	The published fallback split	The routing tier “project defaults” — advisory	Advisory only
`weight.requested`	`library`	A request for weight class, reviewed against the published criteria	No — a request
`attribution.exclude_paths`	none	Paths the attribution algorithm skips	Yes, within the algorithm’s rules
`attribution.bot_identities`	the published bot list	Identities never attributed	Yes, additive to the default list
`contact.waivers`	none	An address shown on the listing for waiver requests	Yes, for display

Rules that constrain what a manifest can do

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.
No prices, bands, or terms. Prices live in one published schedule for everyone (Art. 9). A manifest that tried to set a price would be ignored, and the attempt is worth reporting.
No free-text cause recipients. causes selects among the seven published categories only. There is no field for naming a charity, by design (Art. 7).
causes is advisory. It sets the project-default routing tier. 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.
weight is a request. Self-granted weight would be an attribution exploit within a week. The published criteria and the review are on algorithms and schedule versions.
Attribution overrides can only narrow. You can exclude vendored, generated, or bot contributions; you cannot inflate a contributor’s share, add an identity that did not contribute, or re-point a share at someone else.
Invalid is ignored, never guessed. A malformed file, an unknown field, or a causes block that does not sum to 100 causes the manifest to be ignored in whole with the error published on the repository’s registry page. Silent partial application would make the manifest’s effect unknowable.

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. The verified listing, the badge, and waiver powers come from the claim flow, which proves administrative control; committing a manifest proves nothing about who you are.
Not a channel for terms addressed to administrators. Those live in the claim terms, and only there.

Adoption guide — the one file that actually matters
Leaving — deleting the manifest changes no legal position
Algorithms and schedule versions — how attribution and routing use these fields
Waivers — the powers a claim unlocks