Activity Streams/Primer/Context document versioning

From W3C Wiki

The context document for Activity Streams 2.0 (AS2) is a JSON-LD context document that defines the main namespace prefixes and terms used in Activity Streams 2.0 documents.

The primary context document is at https://www.w3.org/ns/activitystreams . That URL uses content negotiation to return an HTML document describing the Activity Streams 2.0 terms, or a JSON-LD document defining the terms in a machine readable way.

The AS2 specification allows for adding terms and namespaces to the AS2 context document as needed; primarily for popular extensions to the AS2 vocabulary. See Process for Including Extensions in Activity Streams 2.0 for the proposed process for adding extension terms and namespaces.

Versioned snapshots of AS2

Some users of AS2 may not be open to changes in the context document, even if the terms that are added or changed aren't used in their documents. Two important cases are:

  • Implementations that use digital signatures or digital hashes for verification, including the context document. (Possible JSON-LD signatures? TBD)
  • Implementations that use custom namespaces or context documents or namespaces or contexts from far outside the AS2 ecosystem, which might not be accounted for in the extensions policy, and may conflict with newly added terms.

If a user requires that the version of the context document is immutable, they can use a versioned snapshot of the AS2 context.

The versions of the AS2 document are snapshotted and listed at https://www.w3.org/ns/activitystreams-history/ , and listed in reverse chronological order.

For example, a current implementation of ActivityPub could use the following structure: 

 
{
  "@context": ["https://food.example/ns/context/v3", "https://www.w3.org/ns/activitystreams-history/v1.10.jsonld"],
  "type": "Person",
  "name": "Alyssa P. Hacker",
  "favoriteFood": "spaghetti"
}

This would guarantee that the meaning of the "favoriteFood" property defined in the food example context will never be overwritten by the AS2 context.

The downside of using versioned context documents is that there is not an exact match for the canonical context document in the JSON-LD document. Consumers doing a naive check for the context may miss the fact that this is a valid AS2 document.

Guidance

For maximum interoperability, publishers should:

  • Default to using the main context document at https://www.w3.org/ns/activitystreams in your documents.
  • Use a versioned snapshot of the context document if changes to the binary content of that document would invalidate digital signatures or hashes for your document.
  • Use a versioned snapshot of the context document if you also include custom contexts, or contexts from outside the AS2 ecosystem (loosely defined).

Consumers should:

Retrieved from "https://www.w3.org/wiki/index.php?title=Activity_Streams/Primer/Context_document_versioning&oldid=116892"