Document the extension process

[cwebber]

Related to #460 we should document what the process is for submitting an extension to AS2 and make sure all extension terms are currently in the AS2 vocabulary.

[evanp]

I think "document the extension process" and "capture existing terms" are two very different tasks.

[evanp]

So, I think there are four kinds of extensions to AS2 we'd want to track.

0. Established vocabularies. These are existing vocabularies that are adapted for AS2, such as schema.org, vcard, or Dublin Core. For these, we should:

   • Note them on an AS2 wiki page
   • Possibly add the namespaces to the AS2 context document. It's not clear what the acceptance criteria for this would be. It would work like so:

     {
     "@context": {
      "@vocab": "_:",
      "xsd": "http://www.w3.org/2001/XMLSchema#",
      "as": "https://www.w3.org/ns/activitystreams#",
      "ldp": "http://www.w3.org/ns/ldp#",
      "vcard": "http://www.w3.org/2006/vcard/ns#",

   • Possibly add the terms to the AS2 context document when there is no conflict. No clear acceptance criteria yet.

1. Single-implementation extensions. These are things that are really specific for a particular implementation, or are only used once. These should:

   • use a namespace out there somewhere (http://yoursoftware.example/ns)
   • be linked to from the AS2 wiki page

2. Multiple-implementation extensions still in development. For when we're experimenting with new problem areas that need new vocabulary terms, but we're not quite sure about them yet. For these, we should:

   • have a simple way to declare it (for example, on a CG call, or on a well-known wiki page, or with a GH issue)
   • use some kind of sub-namespace of AS2 (https://www.w3.org/ns/activitystreams/dating# or https://www.w3.org/ns/activitystreams#dating?)
   • Implementors use the namespace in their contexts and the namespaced values in their documents:

     {
     "@context": ["https://www.w3.org/ns/activitystreams/",
     {"dating": "https://www.w3.org/ns/activitystreams/dating#"}],
     "type": "Person",
     "dating:seekingGender": "any",
     "dating:geographicalRestrictions": {
         "dating:within": "50km",
         "dating:of": "https://places.example/New_York_City"
     }
     }

3. Well-established extensions. If an extension vocabulary is "well-established" (2+ implementations in production use, say?). For these, we should:

   • Have a way to suggest moving it to the main context document (say, with a GH issue)

   • Add the namespace to the main AS2 context document. For example:

     {
     "@context": {
      "@vocab": "_:",
      "xsd": "http://www.w3.org/2001/XMLSchema#",
      "as": "https://www.w3.org/ns/activitystreams#",
      "ldp": "http://www.w3.org/ns/ldp#",
      "dating": "https://www.w3.org/ns/activitystreams/dating#",

   • Add the terms to the main AS2 context document, if there are no conflicts. For example,

     "seekingGender": "dating:seekingGender",
     "geographicalRestrictions": "dating:geographicalRestrictions"

   • document them on the namespace HTML document.

   • implementations can either use the namespaced terms or the non-namespaced terms, and they'll still have the same identity:

   {
       "@context": "https://www.w3.org/ns/activitystreams/",
       "type": "Person",
       "seekingGender": "any",
       "geographicalRestrictions": {
           "dating:within": "50km",
           "of": "https://places.example/New_York_City"
       }
   }

[cwebber]

Possibly add the namespaces to the AS2 context document. It's not clear what the acceptance criteria for this would be. It would work like so:

I would say it's easy enough to link in another AS2 context that's "fully formed" like this, no need to put them in the AS2 context.

Single-implementation extensions.

Agree with all this section, and aside from documenting them happily this is what is already happening.

use some kind of sub-namespace of AS2 (https://www.w3.org/ns/activitystreams/dating# or https://www.w3.org/ns/activitystreams#dating?)

I agree with this idea a lot, and the rest of what was said. This looks like a good direction to me.

[evanp]

I think there are a couple of reasons we'd include another vocab in the AS2 doc:

• it saves people from writing and re-using complicated @context elements. The closer we can get to having the mainline experience be @context: "https://www.w3.org/ns/activitystreams", the better.
• it gives people a nudge in the right direction. If we think you should use vcard instead of making up your own vocabulary, then including it in the AS2 context gives it a wee bit more authority.

[evanp]

I think schema, vcard, Web security, and Dublin Core would all be good candidates for that treatment.

[evanp]

OK, I created Extension process, so I'm going to close this issue. We can modify that wiki document if we need to change the process.