Skip to content

Commit c3935a7

Browse files
evanpevanp
committed
draft extensions policy
1 parent d5ce002 commit c3935a7

File tree

1 file changed

+236
-0
lines changed

1 file changed

+236
-0
lines changed

‎draft-extensions-policy.html‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset='utf-8'>
5+
<script src='https://www.w3.org/Tools/respec/respec-w3c' async class='remove'></script>
6+
<script class='remove'>
7+
// All config options at https://respec.org/docs/
8+
var respecConfig = {
9+
// Working Groups ids at https://respec.org/w3c/groups/
10+
group: "socialcg",
11+
specStatus: "unofficial",
12+
editors: [{
13+
name: "Evan Prodromou",
14+
url: "https://evanp.me/",
15+
}],
16+
github: {
17+
branch: "main",
18+
repoURL: "w3c/activitystreams",
19+
},
20+
// See https://respec.org/docs/#xref for usage.
21+
xref: ["activitystreams-core", "activitystreams-vocabulary"],
22+
};
23+
</script>
24+
</head>
25+
<body>
26+
<h1 id="title">Process for Including Extensions in Activity Streams 2.0</h1>
27+
<section id='abstract'>
28+
<p>
29+
This document describes the process and criteria for approving extensions
30+
for inclusion in the main Activity Streams 2.0 context document.
31+
</p>
32+
</section>
33+
<section id='sotd'>
34+
<p>
35+
This is a draft Note for publication by the SocialCG. It is not a W3C
36+
recommendation.
37+
</p>
38+
</section>
39+
<section data-dfn-for="SocialCG-Extensions">
40+
<h2>Including Extensions in the Activity Streams 2.0 context document</h2>
41+
<section>
42+
<h2>Motivation</h2>
43+
<p>Activity Streams 2.0 is a vocabulary for representing social data.
44+
It is designed to be extensible, so that new terms can be used by
45+
publishers and consumers.
46+
</p>
47+
<p>
48+
Extensions provide at least the following benefits:
49+
</p>
50+
<ul>
51+
<li>Support specialist vocabularies for specific fields of interest</li>
52+
<li>Model social software patterns that were not common when
53+
Activity Streams 2.0 was originally published</li>
54+
<li>Provide alternate terms or structures for patterns already
55+
represented in Activity Streams 2.0 that improve the vocabulary's clarity
56+
or ease of use</li>
57+
</ul>
58+
<p>
59+
Any publisher can define an extension to Activity Streams 2.0, and use it in
60+
published documents. For example, a publisher could define an extension
61+
that provides a term for the favorite ice cream flavor of a person.
62+
</p>
63+
<figure>
64+
<figcaption>
65+
Context document for the example favorite ice cream flavor context.
66+
</figcaption>
67+
<div id="ex1-context" style="display: block;">
68+
<pre class="example highlight json">
69+
{
70+
"@context": {
71+
"ic": "https://flavors.example/ns/icecream#",
72+
"favoriteIceCreamFlavor": {
73+
"@id": "pdg:favoriteIceCreamFlavor",
74+
"@type": "@id"
75+
},
76+
"Chocolate": "ic:Chocolate",
77+
"Vanilla": "ic:Vanilla",
78+
"Strawberry": "ic:Strawberry",
79+
"Pistachio": "ic:Pistachio"
80+
}
81+
}
82+
</pre>
83+
</div>
84+
</figure>
85+
<p>
86+
This publisher, or any other publisher, can create Activity Streams 2.0
87+
documents that use this extension.
88+
</p>
89+
<figure>
90+
<figcaption>
91+
Example of a person with a favorite flavor of ice cream term.
92+
</figcaption>
93+
<div id="ex1-context" style="display: block;">
94+
<pre class="example highlight json">
95+
{
96+
"@context": [
97+
"https://www.w3.org/ns/activitystreams",
98+
"https://favorites.example/ns/icecream"
99+
],
100+
"id": "https://example.com/people/evan",
101+
"type": "Person",
102+
"name": "Evan Prodromou",
103+
"favoriteIceCreamFlavor": "Pistachio"
104+
}
105+
</pre>
106+
</div>
107+
</figure>
108+
<p>
109+
If the publisher uses different extensions in the same
110+
document with different terms, they will need to resolve
111+
those naming conflicts by hand.
112+
</p>
113+
<figure>
114+
<figcaption>
115+
Example of using two extensions with conflicting terms for "Chocolate"
116+
as an ice cream flavor and as a color of a horse's coat.
117+
</figcaption>
118+
<div id="ex1-context" style="display: block;">
119+
<pre class="example highlight json">
120+
{
121+
"@context": [
122+
"https://www.w3.org/ns/activitystreams",
123+
"https://favorites.example/ns/icecream",
124+
"https://horse.example/ns/colors"
125+
],
126+
"id": "https://example.com/people/evan",
127+
"type": "Person",
128+
"name": "Evan Prodromou",
129+
"favoriteIceCreamFlavor": "ic:Chocolate",
130+
"horseCoatColor": "horse:Chocolate"
131+
}
132+
</pre>
133+
</div>
134+
</figure>
135+
<p>
136+
Any publisher or consumer can implement this extension, subject to
137+
the terms of the creator's license(s), if any.
138+
</p>
139+
<p>
140+
Referencing many extensions can be a burden for publishers and consumers.
141+
Although one or two lines in the @context property of the Activity Streams 2.0
142+
document may not be a problem, ten or twenty could be. In addition,
143+
the more extensions that are used, the more likely it is that there will
144+
be conflicts between terms.
145+
</p>
146+
<p>
147+
If an extension becomes very popular, it may be useful to include its terms
148+
and namespace in the main Activity Streams 2.0 context document.
149+
This will let publishers use the extension without having to include
150+
an additional line of context. It also provides an opportunity to resolve
151+
conflicts between terms in different extensions in one place.
152+
</p>
153+
<p>
154+
This inclusion does not come without a price. First, the Activity Streams 2.0
155+
context document is that much larger, which has a cost in terms of readability,
156+
maintainability, and bandwidth used. In addition, there is work for the
157+
SocialCG in updating, documenting, harmonizing, and maintaining the context
158+
document.
159+
</p>
160+
<p>
161+
This Note describes the criteria that the SocialCG will use to decide
162+
whether the benefits of simplicity and clarity by including extension
163+
terms in the main context document outweigh the costs of doing so.
164+
</p>
165+
<p>
166+
Properly implemented, this process provides a way to make Activity Streams 2.0
167+
a continuously evolving vocabulary, serving new needs for developers and
168+
users, while maintaining the stability of the core terms.
169+
</p>
170+
</section>
171+
<section>
172+
<h2>Process</h2>
173+
<p>These are the steps to including an extension in
174+
the Activity Streams 2.0 context document.</p>
175+
<ol>
176+
<li>Publish the extension for review. Extensions can be published
177+
through the Federation Enhancement Proposal (FEP) process, as Notes of
178+
the SocialCG, through another standardisation process, or by any other
179+
organisations or individuals.
180+
</li>
181+
<li>
182+
Implement the extension; see criteria below for implementation requirements.
183+
</li>
184+
<li>
185+
List the extension in the Activity Streams 2.0 extensions registry.
186+
</li>
187+
<li>
188+
Propose the extension for inclusion. The proposal should include a justification
189+
for inclusion of the extension.
190+
</li>
191+
<li>
192+
Vote on the extension. The SocialCG will vote on whether to include the
193+
extension in the Activity Streams 2.0 context document.
194+
</li>
195+
<li>
196+
Create a draft version of the Activity Streams 2.0 context document including
197+
the extension terms and namespace. This is the time to resolve any conflicts
198+
with existing names in the context document.
199+
</li>
200+
<li>
201+
Test the draft version of the Activity Streams 2.0 context document.
202+
</li>
203+
<li>
204+
Publish the new version of the Activity Streams 2.0 context document.
205+
</li>
206+
</ol>
207+
</section>
208+
<section>
209+
<h2>Criteria</h2>
210+
<p>To be included in the Activity Streams 2.0, extensions should meet these requirements.</p>
211+
<ul>
212+
<li>
213+
A unique namespace, distinct from the Activity Streams 2.0 namespace.
214+
</li>
215+
<li>
216+
A JSON-LD context document at a permanent URL.
217+
</li>
218+
<li>A document that describes the terms and usage of the extension.</li>
219+
<li>
220+
An intellectual property rights policy that is compatible with
221+
inclusion in a W3C specification.
222+
</li>
223+
<li>
224+
Demonstrated implementation by at least two (2) independent publishers.
225+
</li>
226+
<li>
227+
Demonstrated implementation by at least two (2) independent consumers.
228+
</li>
229+
</ul>
230+
</section>
231+
</section>
232+
<section id='conformance'>
233+
<!-- This section is filled automatically by ReSpec. -->
234+
</section>
235+
</body>
236+
</html>

0 commit comments

Comments
 (0)