w3id.org

Appearance

meta/document-identifier-root ​

Severity: warning · Status: enforced · Applies to: ids/**

What ​

The root directory of an identifier should record what the identifier is for and who maintains it. Either of these satisfies the rule:

  • a README.md at the root of the identifier, or
  • maintainer details in the comments of the root .htaccess.

Both are in use across the tree and neither is preferred. The rule asks only where the information is, never what shape it takes.

Why ​

Recording a maintainer at the root claims the identifier. Ownership here is inherited downward: a claim at ids/my-project/ covers everything beneath it, which is how requests to change an identifier have always been assessed. Without one, nothing marks the rest of that tree as taken, and a later contribution can add ids/my-project/something-else/ under a different owner with nothing to say it should not.

That matters more as the handling of contributions is automated. A person reviewing a pull request might recognise that a directory belongs to somebody else. A machine has only what is written down.

The identifiers here are also meant to outlive the people who create them. Somebody arriving at ids/my-project/ a decade from now needs to know what it resolves to and who to ask about it.

Ownership is hierarchical, in both directions ​

Downward: a claim at the root covers the whole tree, so sub-directories need nothing of their own. ids/my-project/v1/ with no README is perfectly correct when ids/my-project/ is documented.

Upward: it does not work. A README three levels down documents that part of the tree. It says nothing about the identifier as a whole, and it leaves the root unclaimed.

A sub-directory may add its own maintainers, and several identifiers work this way. They are additional — read together with the root, not instead of it:

ids/my-project/
├── .htaccess
├── README.md              ← claims the identifier: Firstname Lastname
└── datasets/
    ├── .htaccess
    └── README.md          ← adds a second maintainer for the datasets

This is supported, not merely tolerated. If you see this warning on an identifier that already has a README in a sub-directory, leave that README where it is and add a claim at the root as well. Moving it up to silence the warning destroys a record of who looks after that part of the tree.

Wrong ​

Documented, but the root is unclaimed:

ids/my-project/
├── .htaccess
└── datasets/
    ├── .htaccess
    └── README.md          ← names a maintainer for datasets only

Nothing anywhere:

ids/my-project/
└── .htaccess              ← redirects, but says nothing about who owns this

A README at the root:

ids/my-project/
├── .htaccess
└── README.md

Or the same information in the .htaccess comments, with no README at all:

apache
# my-project -- permanent identifiers for the My Project vocabulary
#
# homepage:
# - https://example.org/my-project/
# maintainers:
# - @exampleuser

RewriteEngine on
RewriteRule ^$ https://example.org/my-project/ [R=302,L]

How to fix ​

Add a README.md at the root of the identifier:

markdown
# my-project

Permanent identifiers for the My Project vocabulary.

<https://w3id.org/my-project/> redirects to <https://example.org/>.

## Contact

- Firstname Lastname, <firstname@example.org>,
  GitHub: [@exampleuser](https://github.com/exampleuser)

Keep it to what the identifier is and who looks after it. Project documentation belongs with the project — see files/only-allowed-names.

Or, if you would rather not add a file, put the same details in comments at the top of the root .htaccess, in the style shown above.

An identifier that exists only to group sub-identifiers has no redirect of its own to serve. An .htaccess there holding nothing but comments is a legitimate way to claim it — files/no-empty-htaccess makes an exception for exactly this case.

How to check ​

Run w3id-check with --rule meta/document-identifier-root to check this rule on its own; without it the tool runs every rule, as the pull request checks do.

sh
node tools/check/bin/w3id-check.js --rule meta/document-identifier-root ids/my-project

A namespace whose sub-names belong to different people has no single maintainer to record at its root. Those are listed under options: meta/document-identifier-root: sharedNamespaces in .w3id-check.yaml, which is a stopgap until a metadata format can express ownership per entry.

Testing your changes covers installing the tool, and what else is worth checking by hand.

See also ​