Skip to content

: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.

39.1 KB
Raw Blame

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 to additions, 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 additions field names for a path. They are separate from the owners of the path (section 3.6).
  • Sensitive path: a path whose resolution has sensitive set to true (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

  1. An ownership file applies to the directory that contains it and to everything below that directory.
  2. 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.
  3. A tool MUST NOT read a file as an ownership file unless the file is named owners.yaml or is an alias file (section 6).
  4. An author MUST NOT put an owners.yaml in a directory where another program reads every YAML file. .github/workflows/ and its subdirectories are always reserved. The root file MAY reserve more locations with reserved_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

  1. A string is a list with one entry.
  2. Each entry MUST be a non-empty string.
  3. A tool MUST keep the order of the list. The first entry is the primary owner.
  4. null makes 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.
  5. An empty list means the file sets no owners. The owners of the nearest ancestor apply.
  6. 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.
  1. A rule with a list of valid patterns is equal to one rule per pattern, in list order, with the same fields.
  2. 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 status keeps the owners of an earlier rule. additions is the exception: each matching rule appends to it (section 3.6).
  3. A resolver MUST NOT apply a rule to a path outside the directory of its file.
  4. 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:

  1. A pattern that starts with / is anchored to that directory.
  2. A pattern with no /, or with only a trailing /, matches at any depth.
  3. A pattern that contains a / other than at the end is anchored to that directory.
  4. A trailing / matches everything below the directory. It does not match the path of the directory itself.
  5. A pattern whose last segment has no wildcard also matches everything below a directory of that name.
  6. * matches any characters except /. ? matches one character except /. ** matches zero or more directories.
  7. [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.
  8. \ escapes the next character.
  9. 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).

  1. A string is a list with one entry. Each entry MUST be a non-empty string, as in 3.1.
  2. 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.
  3. 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.
  4. additions does not change owners. A path with owners of additions and no owners is still unowned.
  5. For the other fields, the nearest file wins. additions is different: the entries of every file in section 4, step 3 and of every matching rule stay in the result. Only inherit: false removes the entries of ancestor files (section 3.3), at file level or through a rule.
  6. 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.
  7. A rule match: '/docs/' matches each path below docs, at any depth. It does not match docs itself (section 3.5, rule 4). The owners of additions for docs come from the other fields and rules on the walk to docs, 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.

  1. 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.
  2. The nearest value wins, as for status. false turns off a true from an ancestor file or from an earlier rule.
  3. sensitive belongs to the paths, not to their owners. A nearer file that changes the owners keeps the value of its ancestors.
  4. sensitive does not change owners. 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.
  5. sensitive does 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.
  6. A consumer that does not request reviews for status: generated (section 3.2) SHOULD still treat a sensitive path as a path to review.
  7. 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:

  1. Normalize P: replace each \ with /. Then, while P starts with ./, remove that ./. Then remove every / at the start and at the end of P.
  2. List the directories from the repository root down to the parent directory of P, root first.
  3. For each directory, find its ownership file. Skip the directory when it has none. An owners.yaml that is not a YAML mapping, or that lacks version: 1 or owners, counts as absent. Section 6 says when an alias file counts as absent.
  4. Start with an empty result: owners unset, status unset, sensitive unset, source unset, additions empty.
  5. For each file found in step 3, in order:
    1. Take the file-level owners, status, inherit, sensitive, and additions.
    2. For each rule in the file that matches P, in file order, replace each of owners, status, inherit, and sensitive that the rule sets. Append each entry of the rule's additions to the file-level additions (section 3.4).
    3. If inherit is false, reset the result to empty.
    4. If owners is null, set the result owners to null and the source to this file.
    5. If owners is a non-empty list, set the result owners to that list and the source to this file.
    6. If status is set, set the result status to it.
    7. If sensitive is set, set the result sensitive to it.
    8. Append each entry of additions to the result additions, unless the result additions already contain it.
  6. Return the resolution:
    • owners: the result owners, or an empty list when unset or null.
    • unowned_by_design: true when the result owners are null.
    • status: the result status, or active when unset.
    • sensitive: the result sensitive, or false when 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 hold P. Take the ancestors of P from the root down. N is the first ancestor that the repository does not hold as a directory, or P itself when it holds all of them as directories. added is N and the additions of the resolution of N. Otherwise, added is 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

  1. A tool that converts a team slug to a GitHub team MUST use the handle @<github_org>/<slug>.
  2. The value MUST NOT contain /.
  3. 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.
  1. A channel is a string that starts with #.
  2. false means the team has no channel for that purpose.
  3. A key of teams MUST be a team slug. It MUST NOT be a person handle.
  4. When the root file declares producers, each key of a notifications mapping MUST name a producer from that list. A mapping MAY leave out any producer. When the root file does not declare producers, any non-empty name is valid.
  5. A tool that cannot read a notifications mapping SHOULD treat it as false. 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 the slack channel.

To find the channel for a team slug T, a purpose, and an optional producer:

  1. If T has no entry in teams, return #T. The result is derived, not declared.
  2. For the purpose "people", check slack.
  3. For the purpose "notifications", check notifications first, then slack.
  4. 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.
  5. When the checked value is a channel, return it. When it is false, return no channel. Both results are declared.
  6. When no field gives a value, return #T as 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).

  1. Each entry of alias_files MUST be a bare file name. It MUST NOT contain / or \, and it MUST NOT be . or ...
  2. An entry MUST NOT be owners.yaml. An entry MUST NOT appear twice.
  3. alias_files MUST NOT hold more than 8 entries. A tool MUST ignore the whole list when it does.
  4. When the root file does not declare alias_files, the only alias file name is product.yaml.
  5. When the root file declares alias_files and the declaration is valid, the alias file names are exactly the declared entries. A tool MUST NOT add product.yaml to a declared list. An empty declared list means the repository has no alias file.
  6. When the root file declares alias_files and a tool ignores the declaration as invalid, the repository has no alias file. A tool MUST NOT fall back to product.yaml there.
  7. A tool MUST NOT read a file as an ownership file unless the file is named owners.yaml or its name is one of the alias file names.
  8. A tool MUST read only the owners and sensitive fields of an alias file. All other fields have no effect on ownership. A sensitive value that is not a boolean has no effect, because the program that owns the alias file validates it.
  9. The owners field MUST be a list of non-empty strings. Otherwise the file counts as absent.
  10. An owners.yaml in the same directory takes precedence. A linter SHOULD report a directory that has both.
  11. When a directory holds more than one alias file, the file with the first name in alias_files takes precedence. A linter SHOULD report that directory.
  12. 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

  1. The consumer MAY pass paths as command arguments.
  2. 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.
  3. The consumer MAY name the repository root. Without one, the resolver MAY find the root itself, for example from the git worktree.
  4. The consumer MAY name the purpose of the channel: people or notifications (section 5.2). The default is people. owners-yaml spells these --purpose slack and --purpose notifications.
  5. The consumer MAY name the producer of the channel (section 5.2). The default is no producer. owners-yaml spells this --producer NAME.
  6. The resolver MUST pass the producer to the channel lookup of section 5.2 for every path of the request.
  7. When the root file declares producers and 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

  1. On success, the resolver MUST write one JSON object to standard output and exit with status 0.

  2. Each key MUST be a requested path after normalization (section 4, step 1). Two requests that normalize to the same path produce one key.

  3. Each value MUST be an object with the members owners, status, slack, and source. It SHOULD also have the members additions, added, and sensitive. The members are:

    Member Type Value
    owners array of strings The resolved owners. Empty when the path is unowned or unowned by design.
    status string The resolved status.
    slack string or null The channel for the requested purpose.
    source string or null The repository-relative path of the file that set the owners.
    additions array of strings The resolved owners of additions (section 3.6), in the order of section 4, step 6.
    added object or null {"path": N, "additions": [...]} from section 4, step 6, or null.
    sensitive boolean Whether the path is sensitive (section 3.7).
  4. A path that is unowned by design has an empty owners array and a non-null source. An unowned path has an empty owners array and a null source.

  5. An unowned path is not an error.

resolution.schema.json describes this object.

7.3 Errors

  1. When the repository root does not exist or cannot be found, the resolver MUST exit with a non-zero status.
  2. On an error, the resolver MUST NOT write a partial response to standard output.

7.4 Compatibility

  1. A consumer MUST ignore members that it does not know.
  2. A resolver MAY add members to a value.
  3. Removing a member, renaming it, or changing its meaning requires a new version of this specification.
  4. A consumer MUST treat a missing additions member as an empty array, a missing added member as null, and a missing sensitive member as false. A resolver that predates a member leaves it out.
  5. For the Python library, the names exported from the top-level owners_yaml package 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.yaml declares. PostHog's own repository declares product.yaml.

  • It removes the placeholder owner team-CHANGEME from every owners and additions list. 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.yaml and 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 added when 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_*.py and *_test.py for pytest, and *.test.* or *.spec.* with a .js, .jsx, .ts, or .tsx extension for Jest. The codeowners setting accepts these keys:

    Key Meaning
    jest_root A directory whose Jest suite runs the tests of other packages.
    jest_root_tests A pattern, relative to the repository root, for the test files that jest_root runs. Those files get an extra spelling relative to jest_root.
    jest_root_packages A 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 owners keeps the status of 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: null records 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.yaml is the default alias file name so that a repository written before alias_files existed resolves the same as it did then. A repository with no alias files sets alias_files: [] and pays no lookups for it.
  • Owners of additions add up. Owners are nearest-file-wins because the union tags too many teams. additions answers 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: owners on 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. additions is routing too: it names owners, and it does not approve or block a change. So is sensitive: it states that a small change matters, and a consumer decides what to do about it.
  • sensitive is 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 as owner:, still fails, because the file then has no owners field. 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.
  • additions does not default to owners. 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 gives alias_files the 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 notifications mapping 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 additions field. Section 7.2 adds the additions member, and a consumer treats a missing member as empty (section 7.4). Section 4 step 1 removes a trailing /, so a request for docs/ resolves the same as docs.
  • 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 the added member, and a consumer treats a missing member as null (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 sensitive field, and section 6 lets an alias file set it. Section 7.2 adds the sensitive member, and a consumer treats a missing member as false (section 7.4). No owners.yaml that was valid before changes meaning. An alias file that already used a sensitive key for another purpose now marks its paths as sensitive.