![]() added syntax highlighting |
||
---|---|---|
.. | ||
README.md | ||
gen_accept.go | ||
gen_activity.go | ||
gen_add.go | ||
gen_announce.go | ||
gen_application.go | ||
gen_arrive.go | ||
gen_article.go | ||
gen_audio.go | ||
gen_block.go | ||
gen_collection.go | ||
gen_collectionpage.go | ||
gen_create.go | ||
gen_delete.go | ||
gen_dislike.go | ||
gen_document.go | ||
gen_event.go | ||
gen_flag.go | ||
gen_follow.go | ||
gen_group.go | ||
gen_ignore.go | ||
gen_image.go | ||
gen_intermediate.go | ||
gen_intransitiveactivity.go | ||
gen_invite.go | ||
gen_join.go | ||
gen_leave.go | ||
gen_like.go | ||
gen_link.go | ||
gen_listen.go | ||
gen_mention.go | ||
gen_move.go | ||
gen_note.go | ||
gen_object.go | ||
gen_offer.go | ||
gen_orderedcollection.go | ||
gen_orderedcollectionpage.go | ||
gen_organization.go | ||
gen_page.go | ||
gen_person.go | ||
gen_place.go | ||
gen_profile.go | ||
gen_question.go | ||
gen_read.go | ||
gen_reject.go | ||
gen_relationship.go | ||
gen_remove.go | ||
gen_service.go | ||
gen_tentativeaccept.go | ||
gen_tentativereject.go | ||
gen_tombstone.go | ||
gen_travel.go | ||
gen_undo.go | ||
gen_update.go | ||
gen_video.go | ||
gen_view.go | ||
gen_vocab.go | ||
vocab_manual_data_test.go | ||
vocab_test.go |
README.md
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
, andactor
properties could be a single value or a JSON array, resulting in JSON deserializing to aninterface{}
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.