:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
The owners.yaml format
Version: 1 Status: stable
This document defines the owners.yaml file format and how a resolver finds the owner of a path from it.
owners-yaml is the reference implementation.
A JSON Schema for editors is in owners.schema.json.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC 2119 RFC 8174 when, and only when, they appear in all capitals, as shown here.
1. Terminology
- Repository: the tree of files that ownership covers. Paths are relative to its root and use
/as the separator. - Ownership file: a file named
owners.yaml, or an alias file (section 6). - Root file: the ownership file in the repository root.
- Owner: a team slug, such as
team-billing, or a person handle, such as@alice. A person handle starts with@. - Primary owner: the first entry of a resolved owners list.
- Rule: an entry of
rules:that replaces fields, or appends toadditions, for the paths its pattern matches. - Resolution: the result of the algorithm in section 4 for one path.
- Unowned: a path whose resolution has no owners and is not unowned by design.
- Unowned by design: a path whose resolution comes from an explicit
owners: null. - Author: a person or program that writes ownership files.
- Tool: a program that reads ownership files. A resolver and a linter are tools.
- Resolver: a tool that computes resolutions (section 4). Section 7 defines a command interface for a resolver.
- Linter: a tool that checks ownership files and reports errors.
- Consumer: a program that uses resolutions, such as a review assigner or a coverage check.
- Addition: a path that a change adds to the repository, such as a new file or directory. A consumer decides which paths count as additions (section 3.6).
- Owners of additions: the owners that the
additionsfield names for a path. They are separate from the owners of the path (section 3.6). - Sensitive path: a path whose resolution has
sensitiveset totrue(section 3.7).
One program can have more than one of these roles. A consumer that reads ownership files itself is also a tool. It is a resolver when it computes resolutions.
2. File placement
- An ownership file applies to the directory that contains it and to everything below that directory.
- An author MUST NOT put more than one ownership file in a directory. Section 6, rules 10 to 12, say which file takes precedence when a directory has more than one.
- A tool MUST NOT read a file as an ownership file unless the file is named
owners.yamlor is an alias file (section 6). - An author MUST NOT put an
owners.yamlin a directory where another program reads every YAML file..github/workflows/and its subdirectories are always reserved. The root file MAY reserve more locations withreserved_dirs(section 5).
3. Fields
An ownership file is a YAML mapping.
| Field | Required | Type | Meaning |
|---|---|---|---|
version |
yes | integer | The format version. MUST be the integer 1, not a boolean, float, or string. |
owners |
yes | string, list of strings, or null |
The owners of the directory. |
status |
no | string | The lifecycle of the code. |
inherit |
no | boolean | Whether fields fall through from ancestor files. Default true. |
rules |
no | list of rule mappings | Per-path overrides inside this directory. |
additions |
no | string or list of strings | The owners of additions below the directory. |
sensitive |
no | boolean | Whether a small change can change behavior far outside the change. |
The root file MAY also carry the repository settings in section 5.
A tool MUST ignore a field that it does not know, at the top level, in a rule, and in a repository setting. The field has no effect on resolution. A linter SHOULD report it as a warning. A linter MUST NOT report it as an error, so that a file written for a later amendment of version 1 still passes an older linter. An amendment of version 1 MAY add a field only when a tool that ignores the field still gives a safe result. A field that a tool cannot safely ignore requires a new version.
3.1 owners
- A string is a list with one entry.
- Each entry MUST be a non-empty string.
- A tool MUST keep the order of the list. The first entry is the primary owner.
nullmakes a path unowned by design when it sets the owners of that path (section 4, step 5.4). A consumer that checks coverage MUST NOT report such a path.- An empty list means the file sets no owners. The owners of the nearest ancestor apply.
- Any other value is an error. The file then sets no owners, as with an empty list, and its other fields still apply.
3.2 status
The value MUST be one of these:
| Value | Meaning |
|---|---|
active |
Maintained code. This is the default. |
deprecated |
Code that is due for removal. |
generated |
Output of a generator. A consumer SHOULD NOT request reviews for this code, unless the path is sensitive (section 3.7). |
vendored |
Third-party code copied into the repository. |
3.3 inherit
inherit: false discards everything that ancestor files contributed, for every path the file applies to.
A rule MAY set inherit to change this for the paths it matches.
3.4 rules
Each rule is a mapping with these fields:
| Field | Required | Type | Meaning |
|---|---|---|---|
match |
yes | string or non-empty list of strings | Patterns, relative to the directory of the file. |
owners |
no | as in 3.1 | Replaces the file-level owners for matching paths. |
status |
no | as in 3.2 | Replaces the file-level status for matching paths. |
inherit |
no | boolean | Replaces the file-level inherit for matching paths. |
additions |
no | as in 3.6 | Appends to the file-level additions for matching paths. |
sensitive |
no | as in 3.7 | Replaces the file-level sensitive for matching paths. |
- A rule with a list of valid patterns is equal to one rule per pattern, in list order, with the same fields.
- Within one file, every rule whose pattern matches a path applies, in file order. Each rule replaces only the fields it sets, so a later rule that sets only
statuskeeps theownersof an earlier rule.additionsis the exception: each matching rule appends to it (section 3.6). - A resolver MUST NOT apply a rule to a path outside the directory of its file.
- A rule with a pattern that breaks section 3.5, rule 9, is an error. A tool MUST ignore the whole rule, including its other patterns, and MAY continue with the rest of the file.
3.5 Patterns
Patterns use the GitHub CODEOWNERS syntax, applied to paths relative to the directory of the file:
- A pattern that starts with
/is anchored to that directory. - A pattern with no
/, or with only a trailing/, matches at any depth. - A pattern that contains a
/other than at the end is anchored to that directory. - A trailing
/matches everything below the directory. It does not match the path of the directory itself. - A pattern whose last segment has no wildcard also matches everything below a directory of that name.
*matches any characters except/.?matches one character except/.**matches zero or more directories.[abc]matches one character from the set.[a-z]matches one character from the range. A[!or a[^at the start negates the set. A set does not match/. A]in the first position is a member of the set, not the end of it. An unclosed[is a literal[. GitHub CODEOWNERS has no character classes, so this rule is an extension of that syntax.\escapes the next character.- A pattern MUST NOT be empty and MUST NOT contain
***.
3.6 additions
owners names the owners of the paths below a directory.
additions names the owners of additions below the directory, such as a new product in a directory of products.
The format only names these owners.
It does not define when a path is an addition.
It does not define what a consumer does with the owners of additions.
A consumer decides both, for example from the change set of a pull request.
A resolver that can see the repository helps with the first: resolved against the version before a change, each path that the change adds carries added, the new part of that path (section 4, step 6).
- A string is a list with one entry. Each entry MUST be a non-empty string, as in 3.1.
- An empty list means that the file or the rule names no owners of additions. A file or a rule with no owners of additions MAY leave the key out.
- Any other value, including
null, is an error. The file or the rule then names no owners of additions, as with an empty list, and its other fields still apply. additionsdoes not changeowners. A path with owners of additions and no owners is still unowned.- For the other fields, the nearest file wins.
additionsis different: the entries of every file in section 4, step 3 and of every matching rule stay in the result. Onlyinherit: falseremoves the entries of ancestor files (section 3.3), at file level or through a rule. - A consumer that asks about a new directory SHOULD use the owners of additions of the directory itself, not of a path below it.
Section 4, step 2 stops at the parent of that path.
So the ownership file of the new directory does not apply.
A rule
match: '/*'in the parent matches each direct child.added(section 4, step 6) gives the new directory and its owners of additions for any path below it. - A rule
match: '/docs/'matches each path belowdocs, at any depth. It does not matchdocsitself (section 3.5, rule 4). The owners of additions fordocscome from the other fields and rules on the walk todocs, as for any other path.
3.7 sensitive
sensitive: true marks paths where a small change can change behavior far outside the change, such as the baseline file of a CI check or a list of exemptions.
The format only states this fact.
A consumer decides what to do with it.
For example, a review assigner can request the owners of a sensitive path for each change to it, whatever the size of the change.
- The value MUST be a boolean. Any other value is an error. The file or the rule then does not set
sensitive, and its other fields still apply. - The nearest value wins, as for
status.falseturns off atruefrom an ancestor file or from an earlier rule. sensitivebelongs to the paths, not to their owners. A nearer file that changes the owners keeps the value of its ancestors.sensitivedoes not changeowners. A sensitive path with no owners is still unowned. A linter SHOULD report a sensitive path that has no owners, unowned by design or not.sensitivedoes not make a review required and does not block a change. Required reviews stay with the code host, for example its CODEOWNERS file and branch protection.- A consumer that does not request reviews for
status: generated(section 3.2) SHOULD still treat a sensitive path as a path to review. - An alias file MAY set
sensitive(section 6).
4. Resolution
A consumer SHOULD get resolutions from a resolver, not by reading ownership files itself.
A consumer chooses which version of the ownership files the resolver reads, through the repository root that it passes (section 7.1).
For example, a consumer can read the version before a change, so that the change cannot alter the owners that apply to it.
A resolver MUST return the same resolution as the steps below for every path. A resolver MAY use a different method. A resolver MAY also remove a placeholder owner that it documents from every list, as owners-yaml does with team-CHANGEME (section 8).
To resolve a path P:
- Normalize
P: replace each\with/. Then, whilePstarts with./, remove that./. Then remove every/at the start and at the end ofP. - List the directories from the repository root down to the parent directory of
P, root first. - For each directory, find its ownership file. Skip the directory when it has none. An
owners.yamlthat is not a YAML mapping, or that lacksversion: 1orowners, counts as absent. Section 6 says when an alias file counts as absent. - Start with an empty result: owners unset, status unset, sensitive unset, source unset, additions empty.
- For each file found in step 3, in order:
- Take the file-level
owners,status,inherit,sensitive, andadditions. - For each rule in the file that matches
P, in file order, replace each ofowners,status,inherit, andsensitivethat the rule sets. Append each entry of the rule'sadditionsto the file-leveladditions(section 3.4). - If
inheritisfalse, reset the result to empty. - If
ownersisnull, set the result owners tonulland the source to this file. - If
ownersis a non-empty list, set the result owners to that list and the source to this file. - If
statusis set, set the result status to it. - If
sensitiveis set, set the result sensitive to it. - Append each entry of
additionsto the result additions, unless the result additions already contain it.
- Take the file-level
- Return the resolution:
owners: the result owners, or an empty list when unset ornull.unowned_by_design:truewhen the result owners arenull.status: the result status, oractivewhen unset.sensitive: the result sensitive, orfalsewhen unset.source: the path of the file that set the owners, or none.slack: the channel from section 5.2, for the requested purpose.additions: the result additions, in the order they were appended.added: only when the resolver can see which paths the repository holds, and the repository does not holdP. Take the ancestors ofPfrom the root down.Nis the first ancestor that the repository does not hold as a directory, orPitself when it holds all of them as directories.addedisNand theadditionsof the resolution ofN. Otherwise,addedis none.
A path is unowned when owners is empty and unowned_by_design is false.
4.1 Field merge
Step 5 applies each file's values to the result as this table shows. The value is the file-level value after step 5.2 applied every matching rule.
| Field | Value in the file | Effect on the result |
|---|---|---|
inherit |
false |
The result resets to empty before the other fields apply. |
inherit |
true or absent |
No effect. |
owners |
non-empty list | Owners become this list. Source becomes this file. |
owners |
[] |
No effect. |
owners |
null |
Owners become null (unowned by design). Source becomes this file. |
status |
set | Status becomes this value. |
status |
absent | No effect. |
sensitive |
set | Sensitive becomes this value. |
sensitive |
absent | No effect. |
additions |
non-empty list | The result additions gain each entry that they do not contain yet, at the end. |
additions |
absent or [] |
No effect. |
4.2 Flow (non-normative)
The numbered steps above are normative. This diagram shows the same walk.
flowchart TD
start([Path P]) --> norm[Normalize P]
norm --> walk[Take the next directory, from the root to the parent of P]
walk --> has{Has an ownership file?}
has -- no --> more
has -- yes --> take[Take the file's owners, status, inherit, sensitive, and additions]
take --> rule{Does a rule match P?}
rule -- yes --> apply[For each matching rule in file order,<br/>replace the owners, status, inherit, and sensitive that it sets,<br/>and append its additions]
rule -- no --> cut
apply --> cut{inherit is false?}
cut -- yes --> reset[Reset the result]
cut -- no --> merge
reset --> merge[Merge owners, status, sensitive, and additions as in 4.1]
merge --> more{More directories?}
more -- yes --> walk
more -- no --> done([Return owners, unowned_by_design, status, sensitive, source, slack, additions, added])
4.3 Conformance
The cases in conformance/ are part of this specification.
A resolver MUST produce the expected result for every case that applies to it.
When the prose and a case disagree, the disagreement is a defect in this specification.
5. Repository settings
An author MUST NOT put these fields in a file other than the root file. A linter MUST report them as errors in any other owners.yaml. They have no effect there.
| Field | Type | Meaning |
|---|---|---|
teams |
mapping | The team channel registry (section 5.2). |
github_org |
string | The GitHub organization of the team slugs. |
producers |
list of strings | The automation names a team can address in notifications. |
reserved_dirs |
list of patterns | Extra reserved locations (section 2, rule 4). The patterns are relative to the repository root. |
alias_files |
list of strings | The other file names that count as ownership files (section 6). Defaults to [product.yaml]. |
codeowners |
mapping | How a CODEOWNERS export spells test file paths. This field is specific to owners-yaml (section 8). |
5.1 github_org
- A tool that converts a team slug to a GitHub team MUST use the handle
@<github_org>/<slug>. - The value MUST NOT contain
/. - A tool MAY accept an override on its command line.
5.2 Team channels
teams maps a team slug to a mapping with these OPTIONAL fields:
| Field | Type | Meaning |
|---|---|---|
slack |
channel or false |
Where people on the team talk. |
notifications |
channel, false, or a mapping of producer to channel or false |
Where automation posts. |
- A channel is a string that starts with
#. falsemeans the team has no channel for that purpose.- A key of
teamsMUST be a team slug. It MUST NOT be a person handle. - When the root file declares
producers, each key of anotificationsmapping MUST name a producer from that list. A mapping MAY leave out any producer. When the root file does not declareproducers, any non-empty name is valid. - A tool that cannot read a
notificationsmapping SHOULD treat it asfalse. A typo then silences automation. Automation does not post to an unwanted channel. One rejected entry makes the whole mapping unreadable. A tool that keeps the other entries sends the rejected producer to theslackchannel.
To find the channel for a team slug T, a purpose, and an optional producer:
- If
Thas no entry inteams, return#T. The result is derived, not declared. - For the purpose "people", check
slack. - For the purpose "notifications", check
notificationsfirst, thenslack. - When the checked value is a mapping, take the value for the producer. With no producer, or when the mapping does not name it, move to the next field.
- When the checked value is a channel, return it. When it is
false, return no channel. Both results are declared. - When no field gives a value, return
#Tas a derived result.
The channel of a path is the channel of its primary owner. When the primary owner is a person handle, the path has no channel. An implementation that answers requests from other programs takes the purpose and the producer from the consumer, as section 7.1 states.
6. Alias files
An alias file is a file with another name that a tool reads as an ownership file, such as a package manifest that already lists owners.
The root file declares the alias files in alias_files (section 5).
- Each entry of
alias_filesMUST be a bare file name. It MUST NOT contain/or\, and it MUST NOT be.or... - An entry MUST NOT be
owners.yaml. An entry MUST NOT appear twice. alias_filesMUST NOT hold more than 8 entries. A tool MUST ignore the whole list when it does.- When the root file does not declare
alias_files, the only alias file name isproduct.yaml. - When the root file declares
alias_filesand the declaration is valid, the alias file names are exactly the declared entries. A tool MUST NOT addproduct.yamlto a declared list. An empty declared list means the repository has no alias file. - When the root file declares
alias_filesand a tool ignores the declaration as invalid, the repository has no alias file. A tool MUST NOT fall back toproduct.yamlthere. - A tool MUST NOT read a file as an ownership file unless the file is named
owners.yamlor its name is one of the alias file names. - A tool MUST read only the
ownersandsensitivefields of an alias file. All other fields have no effect on ownership. Asensitivevalue that is not a boolean has no effect, because the program that owns the alias file validates it. - The
ownersfield MUST be a list of non-empty strings. Otherwise the file counts as absent. - An
owners.yamlin the same directory takes precedence. A linter SHOULD report a directory that has both. - When a directory holds more than one alias file, the file with the first name in
alias_filestakes precedence. A linter SHOULD report that directory. - An alias file in the repository root has no effect. The names come from the root
owners.yaml, and that file takes precedence over any alias file next to it.
A repository with no root file has the default alias file name. A repository whose root file declares an empty alias_files has none, and only owners.yaml sets ownership there.
7. Resolver interface
This section applies to a resolver that answers requests from consumers through a command.
In owners-yaml, both owners resolve --json and python -m owners_yaml implement it.
7.1 Request
- The consumer MAY pass paths as command arguments.
- When the consumer passes no path arguments, the resolver MUST read paths from standard input, one path per line. It MUST remove whitespace at the start and end of each line and MUST skip empty lines.
- The consumer MAY name the repository root. Without one, the resolver MAY find the root itself, for example from the git worktree.
- The consumer MAY name the purpose of the channel: people or notifications (section 5.2). The default is people.
owners-yamlspells these--purpose slackand--purpose notifications. - The consumer MAY name the producer of the channel (section 5.2). The default is no producer.
owners-yamlspells this--producer NAME. - The resolver MUST pass the producer to the channel lookup of section 5.2 for every path of the request.
- When the root file declares
producersand the consumer names a producer that is not in that list, the resolver MUST exit with a non-zero status. The error message MUST list the declared names.
7.2 Response
On success, the resolver MUST write one JSON object to standard output and exit with status 0.
Each key MUST be a requested path after normalization (section 4, step 1). Two requests that normalize to the same path produce one key.
Each value MUST be an object with the members
owners,status,slack, andsource. It SHOULD also have the membersadditions,added, andsensitive. The members are:Member Type Value ownersarray of strings The resolved owners. Empty when the path is unowned or unowned by design. statusstring The resolved status. slackstring or nullThe channel for the requested purpose. sourcestring or nullThe repository-relative path of the file that set the owners. additionsarray of strings The resolved owners of additions (section 3.6), in the order of section 4, step 6. addedobject or null{"path": N, "additions": [...]}from section 4, step 6, ornull.sensitiveboolean Whether the path is sensitive (section 3.7). A path that is unowned by design has an empty
ownersarray and a non-nullsource. An unowned path has an emptyownersarray and anullsource.An unowned path is not an error.
resolution.schema.json describes this object.
7.3 Errors
- When the repository root does not exist or cannot be found, the resolver MUST exit with a non-zero status.
- On an error, the resolver MUST NOT write a partial response to standard output.
7.4 Compatibility
- A consumer MUST ignore members that it does not know.
- A resolver MAY add members to a value.
- Removing a member, renaming it, or changing its meaning requires a new version of this specification.
- A consumer MUST treat a missing
additionsmember as an empty array, a missingaddedmember asnull, and a missingsensitivemember asfalse. A resolver that predates a member leaves it out. - For the Python library, the names exported from the top-level
owners_yamlpackage are the public API. Submodules can change between minor releases.
8. The owners-yaml reference implementation
This section describes the reference implementation. It is not part of the format.
It reads the alias files the root
owners.yamldeclares. PostHog's own repository declaresproduct.yaml.It removes the placeholder owner
team-CHANGEMEfrom everyownersandadditionslist. Section 4 allows this removal.Its linter reports schema errors, unknown fields as warnings, sensitive paths that are unowned as warnings, reserved locations, directories with both an
owners.yamland an alias file, rules that name a tracked directory without the trailing/, rule patterns that match no tracked file, and the number of unowned files. With--live, it also checks team slugs and person handles against the GitHub organization.It reports
addedwhen its source can tell whether the repository holds a path, as its disk source does (TreeSource). A source that reads only the ownership files reports none. It treats a symbolic link as a file, as git does.Its CODEOWNERS export covers test files only:
test_*.pyand*_test.pyfor pytest, and*.test.*or*.spec.*with a.js,.jsx,.ts, or.tsxextension for Jest. Thecodeownerssetting accepts these keys:Key Meaning jest_rootA directory whose Jest suite runs the tests of other packages. jest_root_testsA pattern, relative to the repository root, for the test files that jest_rootruns. Those files get an extra spelling relative tojest_root.jest_root_packagesA directory whose packages do not run their own Jest suite, so their files get no package-relative spelling.
9. Examples (non-normative)
The smallest valid file:
version: 1
owners: team-billing
A file with every directory-level field:
version: 1
owners: [team-billing, '@alice']
status: active
inherit: true
rules:
- match: 'generated/**'
status: generated
- match: 'vendor/'
status: vendored
owners: null
- match: ['migrations/', 'legacy/']
owners: [team-billing, team-data]
- match: 'pricing/allowlist.txt'
sensitive: true
A root file with repository settings:
version: 1
owners: []
github_org: acme
producers: [review-bot, deploy-bot]
reserved_dirs: ['services/*/openapi/**']
alias_files: [package.yaml]
teams:
team-billing:
slack: '#billing'
notifications:
review-bot: '#billing-reviews'
deploy-bot: false
team-legacy:
slack: false
A worked example. The repository has three ownership files:
# owners.yaml
version: 1
owners: team-platform
status: active
teams:
team-billing:
notifications: '#billing-bots'
# billing/owners.yaml
version: 1
owners: [team-billing, '@alice']
status: deprecated
rules:
- match: 'api/'
status: active
- match: 'vendor/'
owners: null
# billing/legacy/owners.yaml
version: 1
owners: []
inherit: false
The trace for billing/api/invoices.py:
| Step | File | Values after the rule | Result after the step |
|---|---|---|---|
| 1 | owners.yaml |
owners [team-platform], status active |
owners [team-platform], status active, source owners.yaml |
| 2 | billing/owners.yaml |
rule api/ matches: owners [team-billing, @alice], status active |
owners [team-billing, @alice], status active, source billing/owners.yaml |
The primary owner is team-billing. Its registry entry has no slack, so the people channel is the derived #team-billing. The notifications channel is #billing-bots.
The results for all four paths, with the purpose "people":
| Path | owners |
unowned_by_design |
status |
source |
slack |
|---|---|---|---|---|---|
billing/api/invoices.py |
[team-billing, @alice] |
false |
active |
billing/owners.yaml |
#team-billing |
billing/jobs/run.py |
[team-billing, @alice] |
false |
deprecated |
billing/owners.yaml |
#team-billing |
billing/vendor/lib.py |
[] |
true |
deprecated |
billing/owners.yaml |
none |
billing/legacy/old.py |
[] |
false |
active |
none | none |
billing/legacy/old.py is unowned: inherit: false drops everything from the parent files, and the file itself sets no owners. The status is the default, active.
Invalid files:
# Missing `version`: the file counts as absent.
owners: team-billing
# `teams` outside the root file is an error.
version: 1
owners: team-billing
teams:
team-billing:
slack: '#billing'
# `***` is not a valid pattern, so the rule is ignored.
version: 1
owners: team-billing
rules:
- match: 'a***b'
owners: team-other
10. Design notes (non-normative)
- Nearest file wins, per field. Kubernetes OWNERS files add approvers from every ancestor, which fits "someone has to approve". For routing, the union tags too many teams, so the nearest file wins. The merge is per field, so a child file that sets only
ownerskeeps thestatusof its ancestors. Rules in one file merge the same way, so a rule that marks generated files does not undo a rule that names their owners. - Rules stay in their file. In a single CODEOWNERS file, a broad pattern added late can take over earlier specific lines. Here a rule changes only its own directory, so a new rule cannot take over paths in another directory.
- Unowned is a decision.
owners: nullrecords that nobody owns a path on purpose. A consumer that checks coverage reports an unowned path. It does not report a path that is unowned by design. - The alias default is for old trees.
product.yamlis the default alias file name so that a repository written beforealias_filesexisted resolves the same as it did then. A repository with no alias files setsalias_files: []and pays no lookups for it. - Owners of additions add up. Owners are nearest-file-wins because the union tags too many teams.
additionsanswers a different question: who owns additions below a directory. If a nested file could drop the owners of additions that an ancestor file names, the answer of the ancestor would not be reliable. A separate field keeps coverage checks correct:ownerson the parent directory would claim every file below it that has no nearer owner. - Routing, not approval. The format answers "who owns this path" for review requests, alerts, and reports. It does not replace a platform's required-approval rules.
additionsis routing too: it names owners, and it does not approve or block a change. So issensitive: it states that a small change matters, and a consumer decides what to do about it. sensitiveis a fact, not an instruction. A field such as "always review" would tell one kind of consumer what to do. A fact about the paths serves every consumer: a review assigner can request the owners, an approval bot can ask for a person, and a report can rank a sensitive unowned path first. It belongs to the paths and not to the owners, so a nearer file that changes the owners keeps it.- Unknown fields are warnings. A typo in an optional field, such as
staus:, then only gives a warning. A typo in a required field, such asowner:, still fails, because the file then has noownersfield. In exchange, a repository can adopt a new field before every tool that reads it upgrades. The amendment rule in section 3 keeps that safe: a field that an older tool ignores must not make its answer wrong. additionsdoes not default toowners. An empty list means that the file names no separate owners of additions. A default would hide which directories have their own owners of additions and which only have owners.- One input format. A resolver reads ownership files only. CODEOWNERS is an export target, and a source for a one-time migration into ownership files, never a second input the resolver reads. The two formats resolve differently: CODEOWNERS takes the last matching line in one file, and this format takes the nearest file, field by field. CODEOWNERS also carries owners and nothing else, so it can say nothing about status or channels. Reading both would make the answer depend on which file a tool found first.
Changelog
- 1 (2026-09): First published version.
- 1, amended (2026-09): Section 3.5 adds
[...]character classes. No pattern that was valid before the amendment changes meaning. Section 6 givesalias_filesthe default[product.yaml], so a root file that does not declare the key now has one alias file instead of none. - 1, amended (2026-09): Section 7.1 adds the producer to the resolver request, so a consumer can reach a team's per-producer
notificationsmapping through an entrypoint. No ownership file changes meaning. - 1, amended (unreleased): Section 3.4 applies every matching rule, field by field. Before, the last matching rule replaced the earlier ones. Section 3.6 adds the optional
additionsfield. Section 7.2 adds theadditionsmember, and a consumer treats a missing member as empty (section 7.4). Section 4 step 1 removes a trailing/, so a request fordocs/resolves the same asdocs. - 1, amended (unreleased): Section 4, step 6 adds
added: for a path that the repository does not hold, the first part of it that the repository does not hold as a directory, with its owners of additions. Section 7.2 adds theaddedmember, and a consumer treats a missing member asnull(section 7.4). No ownership file changes meaning. - 1, amended (unreleased): Section 3 makes a field that a tool does not know a warning, not an error, so a file written for a later amendment still passes an older linter. An amendment adds a field only when a tool that ignores it still gives a safe result. Section 3.7 adds the optional
sensitivefield, and section 6 lets an alias file set it. Section 7.2 adds thesensitivemember, and a consumer treats a missing member asfalse(section 7.4). Noowners.yamlthat was valid before changes meaning. An alias file that already used asensitivekey for another purpose now marks its paths as sensitive.