Skip to content

Commit a7c9015

Browse files
evanpevanp
committed
Reformat, add history of the process
Signed-off-by: Evan Prodromou <evan@openearth.org>
1 parent c3935a7 commit a7c9015

1 file changed

Lines changed: 200 additions & 182 deletions

File tree

‎draft-extensions-policy.html‎

Lines changed: 200 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -36,198 +36,216 @@ <h1 id="title">Process for Including Extensions in Activity Streams 2.0</h1>
3636
recommendation.
3737
</p>
3838
</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>
39+
<section>
40+
<h2>Motivation</h2>
41+
<p>
42+
Activity Streams 2.0, as described in [[[[activitystreams-core]]
43+
and [[activitystreams-vocabulary]] is a vocabulary for representing
44+
social data. It is used by, among others, the [[activitypub]] API and protocol.
45+
It is designed to be extensible, so that new terms can
46+
be used by publishers and consumers.
47+
</p>
48+
<p>
49+
Extensions provide at least the following benefits:
50+
</p>
51+
<ul>
52+
<li>Support specialist vocabularies for specific fields of interest</li>
53+
<li>Model social software patterns that were not common when
54+
Activity Streams 2.0 was originally published</li>
55+
<li>Provide alternate terms or structures for patterns already
56+
represented in Activity Streams 2.0 that improve the vocabulary's clarity
57+
or ease of use</li>
58+
</ul>
59+
<p>
60+
Any publisher can define an extension to Activity Streams 2.0, and use it in
61+
published documents. For example, a publisher could define an extension
62+
that provides a term for the favorite ice cream flavor of a person.
63+
</p>
64+
<figure>
65+
<figcaption>
66+
Context document for the example favorite ice cream flavor context.
67+
</figcaption>
68+
<div id="ex1-context" style="display: block;">
69+
<pre class="example highlight json">
70+
{
71+
"@context": {
72+
"ic": "https://flavors.example/ns/icecream#",
73+
"favoriteIceCreamFlavor": {
74+
"@id": "pdg:favoriteIceCreamFlavor",
75+
"@type": "@id"
76+
},
77+
"Chocolate": "ic:Chocolate",
78+
"Vanilla": "ic:Vanilla",
79+
"Strawberry": "ic:Strawberry",
80+
"Pistachio": "ic:Pistachio"
81+
}
82+
}
83+
</pre>
84+
</div>
85+
</figure>
86+
<p>
87+
This publisher, or any other publisher, can create Activity Streams 2.0
88+
documents that use this extension.
89+
</p>
90+
<figure>
91+
<figcaption>
92+
Example of a person with a favorite flavor of ice cream term.
93+
</figcaption>
94+
<div id="ex1-context" style="display: block;">
95+
<pre class="example highlight json">
96+
{
97+
"@context": [
98+
"https://www.w3.org/ns/activitystreams",
99+
"https://favorites.example/ns/icecream"
100+
],
101+
"id": "https://example.com/people/evan",
102+
"type": "Person",
103+
"name": "Evan Prodromou",
104+
"favoriteIceCreamFlavor": "Pistachio"
105+
}
106+
</pre>
107+
</div>
108+
</figure>
109+
<p>
110+
If the publisher uses different extensions in the same
111+
document with different terms, they will need to resolve
112+
those naming conflicts by hand.
113+
</p>
114+
<figure>
115+
<figcaption>
116+
Example of using two extensions with conflicting terms for "Chocolate"
117+
as an ice cream flavor and as a color of a horse's coat.
118+
</figcaption>
119+
<div id="ex1-context" style="display: block;">
120+
<pre class="example highlight json">
121+
{
122+
"@context": [
123+
"https://www.w3.org/ns/activitystreams",
124+
"https://favorites.example/ns/icecream",
125+
"https://horse.example/ns/colors"
126+
],
127+
"id": "https://example.com/people/evan",
128+
"type": "Person",
129+
"name": "Evan Prodromou",
130+
"favoriteIceCreamFlavor": "ic:Chocolate",
131+
"horseCoatColor": "horse:Chocolate"
132+
}
133+
</pre>
134+
</div>
135+
</figure>
136+
<p>
137+
Any publisher or consumer can implement this extension, subject to
138+
the terms of the creator's license(s), if any.
139+
</p>
140+
<p>
141+
Referencing many extensions can be a burden for publishers and consumers.
142+
Although one or two lines in the @context property of the Activity Streams 2.0
143+
document may not be a problem, ten or twenty could be. In addition,
144+
the more extensions that are used, the more likely it is that there will
145+
be conflicts between terms.
146+
</p>
147+
<p>
148+
If an extension becomes very popular, it may be useful to include its terms
149+
and namespace in the main Activity Streams 2.0 context document.
150+
This will let publishers use the extension without having to include
151+
an additional line of context. It also provides an opportunity to resolve
152+
conflicts between terms in different extensions in the SocialCG.
153+
</p>
154+
<p>
155+
This inclusion does not come without a price. First, the Activity Streams 2.0
156+
context document is that much larger, which has a cost in terms of readability,
157+
maintainability, and bandwidth used. In addition, there is work for the
158+
SocialCG in updating, documenting, harmonizing, and maintaining the context
159+
document.
160+
</p>
161+
<p>
162+
This Note describes the criteria that the SocialCG will use to decide
163+
whether the benefits of simplicity and clarity by including extension
164+
terms in the main context document outweigh the costs of doing so.
165+
</p>
166+
<p>
167+
Properly implemented, this process provides a way to make Activity Streams 2.0
168+
a continuously evolving vocabulary, serving new needs for developers and
169+
users, while maintaining the stability of the core terms.
170+
</p>
171+
</section>
172+
<section>
173+
<h2>Process</h2>
174+
<p>These are the steps to including an extension in
175+
the Activity Streams 2.0 context document.</p>
176+
<ol>
177+
<li><b>Publish the extension for review.</b> Extensions can be published
178+
through the Federation Enhancement Proposal (FEP) process, as Notes of
179+
the SocialCG, through another standardisation process, or by any other
180+
organisations or individuals.
181+
</li>
182+
<li>
183+
<b>Implement the extension.</b> See "Criteria" below for implementation requirements.
184+
</li>
185+
<li>
186+
<b>List the extension in the <a href="https://www.w3.org/wiki/Activity_Streams_extensions">Activity Streams 2.0 extensions registry</a>.</b>
187+
</li>
188+
<li>
189+
<b>Propose the extension for inclusion.</b> The proposal should include a justification
190+
for inclusion of the extension.
191+
</li>
192+
<li>
193+
<b></b>Vote on the extension. The SocialCG will vote on whether to include the
194+
extension in the Activity Streams 2.0 context document.
195+
</li>
196+
<li>
197+
<b>Create a draft version of the Activity Streams 2.0 context document including
198+
the extension terms and namespace. This is the time to resolve any conflicts
199+
with existing names in the context document.</b>
200+
</li>
201+
<li>
202+
<b>Test the draft version of the Activity Streams 2.0 context document.</b>
203+
</li>
204+
<li>
205+
<b>Publish the new version of the Activity Streams 2.0 context document.</b>
206+
</li>
207+
</ol>
208+
</section>
209+
<section>
210+
<h2>Criteria</h2>
211+
<p>To be included in the Activity Streams 2.0, extensions should meet these requirements.</p>
212+
<ul>
187213
<li>
188-
Propose the extension for inclusion. The proposal should include a justification
189-
for inclusion of the extension.
214+
A unique namespace, distinct from the Activity Streams 2.0 namespace.
190215
</li>
191216
<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.
217+
A JSON-LD context document at a permanent URL.
194218
</li>
219+
<li>A document that describes the terms and usage of the extension.</li>
195220
<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.
221+
An intellectual property rights policy that is compatible with
222+
inclusion in a W3C specification.
199223
</li>
200224
<li>
201-
Test the draft version of the Activity Streams 2.0 context document.
225+
Demonstrated implementation by at least two (2) independent publishers.
202226
</li>
203227
<li>
204-
Publish the new version of the Activity Streams 2.0 context document.
228+
Demonstrated implementation by at least two (2) independent consumers.
205229
</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>
230+
</ul>
231+
</section>
232+
<section id='history'>
233+
<h2>Previous Work</h2>
234+
<p>
235+
The section on Extensibility in [[activitystreams-core]] says, in part,
236+
"Some popular extensions are included in the Activity Streams 2.0 namespace
237+
document [...]". It does not define how extensions are added and which
238+
criteria are used to decide whether an extension is popular enough to be
239+
included.
240+
</p>
241+
<p>
242+
<a href="https://www.w3.org/ns/activitystreams#extensions">The section on Extensions in the Activity Streams 2.0 namespace document</a>
243+
says, in part, "The extensions must document their terms in a spec-like way
244+
at a persistant [sic] URL. Approval of extensions will be by the Social Web WG
245+
until it closes, and after that by the followup Community Group. Process and criteria
246+
for extensions approval is being finalised and will be described or linked
247+
to here in due course."
248+
</p>
231249
</section>
232250
<section id='conformance'>
233251
<!-- This section is filled automatically by ReSpec. -->

0 commit comments

Comments
 (0)