From 7afaa4e0ce9cae91e1fe23621b0301ea60884ab4 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Mon, 31 Aug 2026 20:08:15 -0700 Subject: [PATCH 1/2] Rewrite roles for clarity and best practice (fix #106) --- content/user-guide.md | 57 +++++++++++++++---------------------------- 1 file changed, 20 insertions(+), 37 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index bcb9724..b9611a5 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -400,46 +400,29 @@ 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 property is used to define the contribution of a `Person`. It +describes their contribution independently of the person, and allows a person, +through their `id` to be linked to all of their various roles. + +One `Person` can be credited for multiple types of `Role`. This means, for +example, that one person 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. + +`Role` is distinct from other `Person` type properties that such as the +`maintainer` property. Those properties should be defined separately as +top-level properties of the document, containing at least one `Person`. +{.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": [ From 30d914b1cc0470d9b08045e0a20ddfe20e18501d Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 8 Sep 2026 12:38:56 -0700 Subject: [PATCH 2/2] Clarify maintainer should still be used with role etc, and fix earlier wording --- content/user-guide.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index b9611a5..741827e 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -400,22 +400,23 @@ refer to a consistent identity of an individual. ### Roles -The `Role` type property is used to define the contribution of a `Person`. It -describes their contribution independently of the person, and allows a person, -through their `id` to be linked to all of their various roles. +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 types of `Role`. This means, for -example, that one person can be credited as "Developer" and for "Documentation". +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. -`Role` is distinct from other `Person` type properties that such as the -`maintainer` property. Those properties should be defined separately as -top-level properties of the document, containing at least one `Person`. +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} -The `roleName` property can have any descriptive role name desired, or a URL. +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.