activity/vocab

vocab

The vocab package provides static types for Core and Extended types to the ActivityStream Vocabulary. The library is battle-tested against all 159 examples in the Vocabulary specification linked above in addition to unit tests.

Its mission is simple: Provide meaningful static types for the ActivityStream Vocabulary in golang.

This library is entirely code-generated by the tools/vocab/gen library and tools/vocab tool. Run go generate to refresh the library, which which requires $GOPATH/bin to be on your $PATH.

This library's API is huge!

The W3C does not require client applications to support all of these use cases. The W3C only requires that "all implementations must at least be capable of serializing and deserializing the Extended properties in accordance with the Activity Streams 2.0 Core Syntax," which what this library and the activity/streams libraries do for clients. This library's API is large to permit clients to use as much or as little as desired.

What it does

This library is given a map[string]interface{}, presumably from an ActivityStream or JSON-LD kind of JSON, and returns a static type that provides a statically-typed API.

For example, consider an application that receives the simple ActivityStream Vocabulary object in the following JSON:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "name": "Automated Train",
  "content": "Now arriving at sector C test labs and control facilities.",
  "published": "1998-11-08T08:47Z",
  "actor": "http://freeman.example.org"
}

In order to extract this information, the application can use encoding/json to obtain a map[string]interface{} of this data. It cannot use a raw direct type because JSON-LD, and therefore the ActivityStream Vocabulary, permit the same property to be any of a JSON string, a JSON object, or a JSON array in most conditions. Consider:

• The type, name, content, and actor properties could be a single value or a JSON array, resulting in JSON deserializing to an interface{} or []interface{} for these properties
• Any of these properties could be a string value or need to be treated as an IRI
• The published time conforms to RFC3339 with the exception that seconds may be omitted

Therefore, trying to statically determine this with typical JSON tagging does not work:

type NaiveActivity struct {
  type string `json:"Type"`   // Not OK, cannot handle array of strings
  name []string `json:"Name"` // Not OK, cannot handle single values
  // ...
  published time.Time `...`   // Not OK, cannot handle when seconds are omitted
}

This is the motivation for this library.

All of these considerations are presented as:

type Note struct { ... }
func (n *Note) NameLen() int { ... }
func (n *Note) IsNameString(index int) bool { ... }
func (n *Note) IsNameIRI(index int) bool { ... }
func (n *Note) GetNameString(index int) string { ... }
// And so on

Note that the resulting API and property type possibilities is large. This is a natural consequence of the specification being built on top of JSON-LD.

What it doesn't do

This library does not use the reflect package at all. It prioritizes minimizing dependencies and speed over binary size.

The ActivityStream specification is built on top of JSON-LD, which uses JSON. This library should be used with encoding/json in order to transform a raw string to a map[string]interface{} and then to these static types.

This library does not set the "@context" property required when sending serialized data. Clients are in charge of setting it to "https://www.w3.org/ns/activitystreams".

This implementation is heavily opinionated against understanding JSON-LD due to its sacrifice of semantic meaning, significant increase of complexity, even weaker typing, and increased exposure to partially-understood messages. These costs earn a degree of flexibility that is not needed for the ActivityStream Vocabulary.

This library is not a JSON-LD parser, and by design does not implement any further understanding of JSON-LD that may be outlined in the W3C's JSON-LD specification. Furthermore, it does not implement any of the JSON-LD processing algorithms. If this functionality is strictly needed, or this library is not suitable, please see piprate/json-gold/ld and its documentation.

Other considerations

This library is entirely code-generated. Determined clients can add their own custom extended types to the tools/defs library and generate a useful type. However, this process is purposefully painful to force clients to seriously consider whether they need their own custom type.

The code-generation aspect also allows the specification to be translated into declarative data, which permits certain kinds of validation and verification. This has resulted in feedback to the specification and the W3C working group.

Thanks

Many thanks to those who have worked on JSON-LD, ActivityStreams Core, and the ActivityStreams Vocabulary specifications.