Extension process proposal

This proposal was rejected by the social CG on 12 September 2018. It's saved here for historical purposes.

External namespaces and terms can always be used by adding them to the @context property of an AS2 document.

It is helpful to developers if we:

1. document namespace URLs they may see in other documents
2. simplify the @context property by including a well-known prefix in the AS2 context document
3. simplify terms by aliasing them in the AS2 context document so they don't need a prefix

There are four kinds of extensions to AS2 we want to track.

Established vocabularies

These are existing vocabularies that are used in AS2 documents, such as schema.org, vcard, or Dublin Core. For these, we should:

• Note them on the AS2 wiki page Extensions
• Possibly add the namespaces to the AS2 context document. No fixed acceptance criteria, but 2+ interoperable implementations is a good start. The best way to discuss is via a Github issue. 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 with existing terms. There is no fixed acceptance criteria, but the principle is to reduce errors and effort by not requiring a prefix. The best way to discuss is via a Github issue.

Single-implementation namespaces

These are namespaces that are really specific for a particular implementation, or are only used once. For example, pump.io includes internal database IDs and other debugging information under a pump.io namespace.

These extensions should:

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

Extensions on track for publication

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:

• Declare it with a Github issue

• define a namespace to be used by all implementations, such as https://as2dating.example/ns/

• Implementors use the namespace in their contexts and the namespaced values in their documents:

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

• Note them on the AS2 wiki page Extensions

Mature extensions

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

• Suggest moving it to the main context document with a GitHub 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://as2dating.example/ns/",

• 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"
      }
  }