Skip to content

Commit

Permalink
draft extensions policy
Browse files Browse the repository at this point in the history
  • Loading branch information
@evanp
evanp committed Jun 24, 2023
1 parent d5ce002 commit c3935a7
Showing 1 changed file with 236 additions and 0 deletions.
236 changes: 236 additions & 0 deletions draft-extensions-policy.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<script src='https://www.w3.org/Tools/respec/respec-w3c' async class='remove'></script>
<script class='remove'>
// All config options at https://respec.org/docs/
var respecConfig = {
// Working Groups ids at https://respec.org/w3c/groups/
group: "socialcg",
specStatus: "unofficial",
editors: [{
name: "Evan Prodromou",
url: "https://evanp.me/",
}],
github: {
branch: "main",
repoURL: "w3c/activitystreams",
},
// See https://respec.org/docs/#xref for usage.
xref: ["activitystreams-core", "activitystreams-vocabulary"],
};
</script>
</head>
<body>
<h1 id="title">Process for Including Extensions in Activity Streams 2.0</h1>
<section id='abstract'>
<p>
This document describes the process and criteria for approving extensions
for inclusion in the main Activity Streams 2.0 context document.
</p>
</section>
<section id='sotd'>
<p>
This is a draft Note for publication by the SocialCG. It is not a W3C
recommendation.
</p>
</section>
<section data-dfn-for="SocialCG-Extensions">
<h2>Including Extensions in the Activity Streams 2.0 context document</h2>
<section>
<h2>Motivation</h2>
<p>Activity Streams 2.0 is a vocabulary for representing social data.
It is designed to be extensible, so that new terms can be used by
publishers and consumers.
</p>
<p>
Extensions provide at least the following benefits:
</p>
<ul>
<li>Support specialist vocabularies for specific fields of interest</li>
<li>Model social software patterns that were not common when
Activity Streams 2.0 was originally published</li>
<li>Provide alternate terms or structures for patterns already
represented in Activity Streams 2.0 that improve the vocabulary's clarity
or ease of use</li>
</ul>
<p>
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.
</p>
<figure>
<figcaption>
Context document for the example favorite ice cream flavor context.
</figcaption>
<div id="ex1-context" style="display: block;">
<pre class="example highlight json">
{
"@context": {
"ic": "https://flavors.example/ns/icecream#",
"favoriteIceCreamFlavor": {
"@id": "pdg:favoriteIceCreamFlavor",
"@type": "@id"
},
"Chocolate": "ic:Chocolate",
"Vanilla": "ic:Vanilla",
"Strawberry": "ic:Strawberry",
"Pistachio": "ic:Pistachio"
}
}
</pre>
</div>
</figure>
<p>
This publisher, or any other publisher, can create Activity Streams 2.0
documents that use this extension.
</p>
<figure>
<figcaption>
Example of a person with a favorite flavor of ice cream term.
</figcaption>
<div id="ex1-context" style="display: block;">
<pre class="example highlight json">
{
"@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"
}
</pre>
</div>
</figure>
<p>
If the publisher uses different extensions in the same
document with different terms, they will need to resolve
those naming conflicts by hand.
</p>
<figure>
<figcaption>
Example of using two extensions with conflicting terms for "Chocolate"
as an ice cream flavor and as a color of a horse's coat.
</figcaption>
<div id="ex1-context" style="display: block;">
<pre class="example highlight json">
{
"@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"
}
</pre>
</div>
</figure>
<p>
Any publisher or consumer can implement this extension, subject to
the terms of the creator's license(s), if any.
</p>
<p>
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.
</p>
<p>
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 one place.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section>
<h2>Process</h2>
<p>These are the steps to including an extension in
the Activity Streams 2.0 context document.</p>
<ol>
<li>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.
</li>
<li>
Implement the extension; see criteria below for implementation requirements.
</li>
<li>
List the extension in the Activity Streams 2.0 extensions registry.
</li>
<li>
Propose the extension for inclusion. The proposal should include a justification
for inclusion of the extension.
</li>
<li>
Vote on the extension. The SocialCG will vote on whether to include the
extension in the Activity Streams 2.0 context document.
</li>
<li>
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.
</li>
<li>
Test the draft version of the Activity Streams 2.0 context document.
</li>
<li>
Publish the new version of the Activity Streams 2.0 context document.
</li>
</ol>
</section>
<section>
<h2>Criteria</h2>
<p>To be included in the Activity Streams 2.0, extensions should meet these requirements.</p>
<ul>
<li>
A unique namespace, distinct from the Activity Streams 2.0 namespace.
</li>
<li>
A JSON-LD context document at a permanent URL.
</li>
<li>A document that describes the terms and usage of the extension.</li>
<li>
An intellectual property rights policy that is compatible with
inclusion in a W3C specification.
</li>
<li>
Demonstrated implementation by at least two (2) independent publishers.
</li>
<li>
Demonstrated implementation by at least two (2) independent consumers.
</li>
</ul>
</section>
</section>
<section id='conformance'>
<!-- This section is filled automatically by ReSpec. -->
</section>
</body>
</html>

0 comments on commit c3935a7

Please sign in to comment.