forked from w3c/activitystreams
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-extensions-policy.html
278 lines (278 loc) · 11.4 KB
/
draft-extensions-policy.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
<!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>
<h2>Motivation</h2>
<p>
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.
</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": "ic: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 the SocialCG.
</p>
<p>
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.
</p>
<figure>
<figcaption>
Theoretical example of using the favorite ice cream flavor term
after it has been included in the main Activity Streams 2.0 context
document.
</figcaption>
<div id="ex1-context" style="display: block;">
<pre class="example highlight json">
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "https://example.com/people/evan",
"type": "Person",
"name": "Evan Prodromou",
"favoriteIceCreamFlavor": "Chocolate"
}
</pre>
</div>
</figure>
<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><b>Publish the extension for review.</b> 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.
</li>
<li>
<b>Implement the extension.</b> See "Criteria" below for implementation requirements.
</li>
<li>
<b>List the extension in the <a href="https://www.w3.org/wiki/Activity_Streams_extensions">Activity Streams 2.0 extensions registry</a>.</b>
</li>
<li>
<b>Propose the extension for inclusion.</b> The proposal should include a justification
for inclusion of the extension.
</li>
<li>
<b>Vote on the extension.</b> The SocialCG will vote on whether to include the
extension in the Activity Streams 2.0 context document.
</li>
<li>
<b>Create a draft version of the Activity Streams 2.0 context document including
the extension terms and namespace.</b> This is the time to resolve any conflicts
with existing names in the context document.
</li>
<li>
<b>Test the draft version of the Activity Streams 2.0 context document.</b>
</li>
<li>
<b>Publish the new version of the Activity Streams 2.0 context document.</b>
</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 id='history'>
<h2>Previous Work</h2>
<p>
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.
</p>
<p>
<a href="https://www.w3.org/ns/activitystreams#extensions">The section on Extensions in the Activity Streams 2.0 namespace document</a>
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."
</p>
</section>
<section id='conformance'>
<!-- This section is filled automatically by ReSpec. -->
</section>
</body>
</html>