Process for Including Extensions in Activity Streams 2.0

This document describes the process and criteria for approving extensions for inclusion in the main Activity Streams 2.0 context document.

This is a draft Note for publication by the SocialCG. It is not a W3C recommendation.

Motivation

Activity Streams 2.0, as described in [[activitystreams-core]] and [[activitystreams-vocabulary]] is a vocabulary for representing social data. It is used by, among others, the [[activitypub]] API and protocol. It is designed to be extensible, so that new terms can be used by publishers and consumers.

Extensions provide at least the following benefits:

• Support specialist vocabularies for specific fields of interest
• Model social software patterns that were not common when Activity Streams 2.0 was originally published
• Provide alternate terms or structures for patterns already represented in Activity Streams 2.0 that improve the vocabulary's clarity or ease of use

Any publisher can define an extension to Activity Streams 2.0, and use it in published documents. For example, a publisher could define an extension that provides a term for the favorite ice cream flavor of a person.

              {
                  "@context": {
                      "ic": "https://flavors.example/ns/icecream#",
                      "favoriteIceCreamFlavor": {
                          "@id": "ic:favoriteIceCreamFlavor",
                          "@type": "@id"
                      },
                      "Chocolate": "ic:Chocolate",
                      "Vanilla": "ic:Vanilla",
                      "Strawberry": "ic:Strawberry",
                      "Pistachio": "ic:Pistachio"
                  }
              }
            

This publisher, or any other publisher, can create Activity Streams 2.0 documents that use this extension.

              {
                  "@context": [
                      "https://www.w3.org/ns/activitystreams",
                      "https://favorites.example/ns/icecream"
                  ],
                  "id": "https://example.com/people/evan",
                  "type": "Person",
                  "name": "Evan Prodromou",
                  "favoriteIceCreamFlavor": "Pistachio"
              }
            

If the publisher uses different extensions in the same document with different terms, they will need to resolve those naming conflicts by hand.

              {
                  "@context": [
                      "https://www.w3.org/ns/activitystreams",
                      "https://favorites.example/ns/icecream",
                      "https://horse.example/ns/colors"
                  ],
                  "id": "https://example.com/people/evan",
                  "type": "Person",
                  "name": "Evan Prodromou",
                  "favoriteIceCreamFlavor": "ic:Chocolate",
                  "horseCoatColor": "horse:Chocolate"
              }
            

Any publisher or consumer can implement this extension, subject to the terms of the creator's license(s), if any.

Referencing many extensions can be a burden for publishers and consumers. Although one or two lines in the @context property of the Activity Streams 2.0 document may not be a problem, ten or twenty could be. In addition, the more extensions that are used, the more likely it is that there will be conflicts between terms.

If an extension becomes very popular, it may be useful to include its terms and namespace in the main Activity Streams 2.0 context document. This will let publishers use the extension without having to include an additional line of context. It also provides an opportunity to resolve conflicts between terms in different extensions in the SocialCG.

Thereafter, publishers will not need to include the extension's context URL in their documents. The extension's terms will be available for all documents that use the Activity Streams 2.0 context, without requiring a namespace prefix.

              {
                  "@context": "https://www.w3.org/ns/activitystreams",
                  "id": "https://example.com/people/evan",
                  "type": "Person",
                  "name": "Evan Prodromou",
                  "favoriteIceCreamFlavor": "Chocolate"
              }
            

This inclusion does not come without a price. First, the Activity Streams 2.0 context document is that much larger, which has a cost in terms of readability, maintainability, and bandwidth used. In addition, there is work for the SocialCG in updating, documenting, harmonizing, and maintaining the context document.

This Note describes the criteria that the SocialCG will use to decide whether the benefits of simplicity and clarity by including extension terms in the main context document outweigh the costs of doing so.

Properly implemented, this process provides a way to make Activity Streams 2.0 a continuously evolving vocabulary, serving new needs for developers and users, while maintaining the stability of the core terms.

Process

These are the steps to including an extension in the Activity Streams 2.0 context document.

1. Publish the extension for review. Extensions can be published through the Federation Enhancement Proposal (FEP) process, as Notes of the SocialCG, through another standardisation process, or by any other organisations or individuals. See "Criteria" below for required content.
2. Implement the extension. See "Criteria" below for implementation requirements.
3. List the extension in the Activity Streams 2.0 extensions registry.
4. Propose the extension for inclusion. The proposal should include a justification for inclusion of the extension.
5. Vote on the extension. The SocialCG will vote on whether to include the extension in the Activity Streams 2.0 context document.
6. Create a draft version of the Activity Streams 2.0 context document including the extension terms and namespace. This is the time to resolve any conflicts with existing names in the context document.
7. Test the draft version of the Activity Streams 2.0 context document.
8. Publish the new version of the Activity Streams 2.0 context document.

Criteria

To be included in the Activity Streams 2.0, extensions SHOULD meet these requirements.

• A unique namespace, distinct from the Activity Streams 2.0 namespace.
• A JSON-LD context document at a permanent URL.
• A document that describes the terms and usage of the extension.
• An intellectual property rights policy that is compatible with inclusion in a W3C specification.
• Demonstrated implementation by at least two (2) independent publishers.
• Demonstrated implementation by at least two (2) independent consumers.

Extensions to be included MAY meet these criteria:

• A security review, either by the submitter, members of the SocialCG, or by the SecurityIG].
• A privacy review, either by the submitter, members of the SocialCG, or others.
• An accessibility (A11Y) review.
• An internationalisation (I18N) review.

Previous Work

The section on Extensibility in [[activitystreams-core]] says, in part, "Some popular extensions are included in the Activity Streams 2.0 namespace document [...]". It does not define how extensions are added and which criteria are used to decide whether an extension is popular enough to be included.

The section on Extensions in the Activity Streams 2.0 namespace document says, in part, "The extensions must document their terms in a spec-like way at a persistant [sic] URL. Approval of extensions will be by the Social Web WG until it closes, and after that by the followup Community Group. Process and criteria for extensions approval is being finalised and will be described or linked to here in due course."

• 2023-09-29: Add review criteria.
• 2023-06-24: First draft.