Skip to content

Rewrite roles for clarity and best practice (fix #106) #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moranegg merged 2 commits into from
Sep 11, 2026
Merged

Rewrite roles for clarity and best practice (fix #106) #136

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7afaa4e
Rewrite roles for clarity and best practice (fix #106)
meldra Sep 1, 2026
30d914b
Clarify maintainer should still be used with role etc, and fix earlie…
meldra Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 21 additions & 37 deletions content/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -400,46 +400,30 @@ refer to a consistent identity of an individual.

### Roles

The `Role` type property is used within the `author` or `contributor`
properties to further define the participation of a `Person`. The property is
intended to clarify the functional area the individual with the free-form
value of the `roleName` property.

An example author role:

```json
"author": [
...
{
"roleName": "User Experience Design",
"schema:author": "https://github.com/octocat",
"type": "Role"
},
...
]
```

Or a contributor:
The `Role` type is used to define the contribution of a `Person`, describing
their contribution independently. It allows a `Person`, through their `id`,
to be linked to all of their various roles.

One `Person` can be credited for multiple kinds of `Role`. This means, for
example, that someone can be credited as "Developer" and for "Documentation".
Multiple people can be attributed to the same `roleName`. A `Role` can also be
defined for a specific period of time by using the `startDate` and `endDate`
properties.

Defining a `Role` is not a substitute for defining properties that are named
like roles. For example, the maintainer(s) may change over time and may retain
attribution after their `endDate`. For clarity `maintainer` should only contain
the current holder(s) of that position.
{.tip}

```json
"contributor": [
...
{
"roleName": "Documentation",
"schema:author": "https://github.com/octocat",
"type": "Role"
},
...
]
```
The `roleName` property can have any descriptive role name desired, or a URL
It defines the type of contribution. The use of `id` avoids duplicating the
details for a person, which keeps them consistent and easy to update.

This is distinct from the `maintainer` property, which should be defined
independently as a top-level property of the document, containing at least
one `Person`.
The `Role` must link to a `Person` also defined in the document, typically
under `author` or `contributor`. The example below demonstrates the `id` and
`schema:author` values providing this link.

The `Role` must link to a `Person` previously defined in the top-level
property. The example below demonstrates the `id` and `schema:author` values
providing this link.

```json
"author": [
Expand Down
Loading