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 usual 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.

Please consider using the activity/streams library instead.

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

All of these considerations are presented much more nicely by this library:

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. It is recommended for applications to use the activity/streams convenience library instead, or create their own convenience types:

type MyNote struct {
  note *vocab.Note
}

func (n *Note) Name() (string, bool) { /* Use note.NameLen, etc. */ }
// And so on

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 led to giving the following feedback to the specification:

• Inconsistencies between property domains and type properties
• Please clarify "items" and "orderedItems" properties
• Expectations around IRI resolution
• Examples Contradict Specification
• Tombstone "formerType" Property Range Needs Clarification
• Example 60 Missing @context Property
• Stylistic Consistency For Non-Functional Single-Value JSON in Examples
• Spec does not clarify non-functional natural language values when mapped
• Example 102: url property missing type: "Link"
• Example 146: Missing Z in startTime
• Example 150: Latitude/Longitude are not xsd:float

Thanks

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