|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 16-Nov-2018 | - |
| README.md | H A D | 16-Nov-2018 | 5.3 KiB | 129 | 100 |
| gen_accept.go | H A D | 16-Nov-2018 | 205.7 KiB | 7,062 | 4,665 |
| gen_activity.go | H A D | 16-Nov-2018 | 207.2 KiB | 7,062 | 4,665 |
| gen_add.go | H A D | 16-Nov-2018 | 203.7 KiB | 7,062 | 4,665 |
| gen_announce.go | H A D | 16-Nov-2018 | 207 KiB | 7,062 | 4,665 |
| gen_application.go | H A D | 16-Nov-2018 | 176.9 KiB | 6,007 | 3,967 |
| gen_arrive.go | H A D | 16-Nov-2018 | 201.5 KiB | 6,917 | 4,567 |
| gen_article.go | H A D | 16-Nov-2018 | 174.5 KiB | 6,007 | 3,967 |
| gen_audio.go | H A D | 16-Nov-2018 | 173.3 KiB | 6,007 | 3,967 |
| gen_block.go | H A D | 16-Nov-2018 | 205.1 KiB | 7,062 | 4,665 |
| gen_collection.go | H A D | 16-Nov-2018 | 193.3 KiB | 6,600 | 4,343 |
| gen_collectionpage.go | H A D | 16-Nov-2018 | 204.8 KiB | 6,924 | 4,544 |
| gen_create.go | H A D | 16-Nov-2018 | 205.5 KiB | 7,062 | 4,665 |
| gen_delete.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_dislike.go | H A D | 16-Nov-2018 | 206.2 KiB | 7,062 | 4,665 |
| gen_document.go | H A D | 16-Nov-2018 | 175.1 KiB | 6,007 | 3,967 |
| gen_event.go | H A D | 16-Nov-2018 | 173.3 KiB | 6,007 | 3,967 |
| gen_flag.go | H A D | 16-Nov-2018 | 204.3 KiB | 7,062 | 4,665 |
| gen_follow.go | H A D | 16-Nov-2018 | 205.8 KiB | 7,062 | 4,665 |
| gen_group.go | H A D | 16-Nov-2018 | 173.4 KiB | 6,007 | 3,967 |
| gen_ignore.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_image.go | H A D | 16-Nov-2018 | 177.8 KiB | 6,181 | 4,077 |
| gen_intermediate.go | H A D | 16-Nov-2018 | 200.4 KiB | 7,976 | 6,408 |
| gen_intransitiveactivity.go | H A D | 16-Nov-2018 | 217.8 KiB | 7,005 | 4,613 |
| gen_invite.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_join.go | H A D | 16-Nov-2018 | 204.2 KiB | 7,062 | 4,665 |
| gen_leave.go | H A D | 16-Nov-2018 | 204.9 KiB | 7,062 | 4,665 |
| gen_like.go | H A D | 16-Nov-2018 | 204.2 KiB | 7,062 | 4,665 |
| gen_link.go | H A D | 16-Nov-2018 | 45.8 KiB | 1,639 | 1,095 |
| gen_listen.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_mention.go | H A D | 16-Nov-2018 | 45.8 KiB | 1,639 | 1,095 |
| gen_move.go | H A D | 16-Nov-2018 | 204.3 KiB | 7,062 | 4,665 |
| gen_note.go | H A D | 16-Nov-2018 | 172.8 KiB | 6,007 | 3,967 |
| gen_object.go | H A D | 16-Nov-2018 | 174.1 KiB | 6,007 | 3,967 |
| gen_offer.go | H A D | 16-Nov-2018 | 204.9 KiB | 7,062 | 4,665 |
| gen_orderedcollection.go | H A D | 16-Nov-2018 | 208.4 KiB | 6,720 | 4,406 |
| gen_orderedcollectionpage.go | H A D | 16-Nov-2018 | 223.2 KiB | 7,131 | 4,662 |
| gen_organization.go | H A D | 16-Nov-2018 | 177.4 KiB | 6,007 | 3,967 |
| gen_page.go | H A D | 16-Nov-2018 | 172.7 KiB | 6,007 | 3,967 |
| gen_person.go | H A D | 16-Nov-2018 | 173.9 KiB | 6,007 | 3,967 |
| gen_place.go | H A D | 16-Nov-2018 | 185 KiB | 6,442 | 4,242 |
| gen_profile.go | H A D | 16-Nov-2018 | 177.1 KiB | 6,094 | 4,022 |
| gen_question.go | H A D | 16-Nov-2018 | 221.5 KiB | 7,537 | 4,971 |
| gen_read.go | H A D | 16-Nov-2018 | 204.2 KiB | 7,062 | 4,665 |
| gen_reject.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_relationship.go | H A D | 16-Nov-2018 | 187.5 KiB | 6,347 | 4,187 |
| gen_remove.go | H A D | 16-Nov-2018 | 205.6 KiB | 7,062 | 4,665 |
| gen_service.go | H A D | 16-Nov-2018 | 174.5 KiB | 6,007 | 3,967 |
| gen_tentativeaccept.go | H A D | 16-Nov-2018 | 211.8 KiB | 7,062 | 4,665 |
| gen_tentativereject.go | H A D | 16-Nov-2018 | 211.8 KiB | 7,062 | 4,665 |
| gen_tombstone.go | H A D | 16-Nov-2018 | 184.2 KiB | 6,276 | 4,142 |
| gen_travel.go | H A D | 16-Nov-2018 | 201.5 KiB | 6,917 | 4,567 |
| gen_undo.go | H A D | 16-Nov-2018 | 204.4 KiB | 7,062 | 4,665 |
| gen_update.go | H A D | 16-Nov-2018 | 205.7 KiB | 7,062 | 4,665 |
| gen_video.go | H A D | 16-Nov-2018 | 173.3 KiB | 6,007 | 3,967 |
| gen_view.go | H A D | 16-Nov-2018 | 204.2 KiB | 7,062 | 4,665 |
| gen_vocab.go | H A D | 16-Nov-2018 | 28.4 KiB | 1,405 | 1,124 |
| vocab_manual_data_test.go | H A D | 16-Nov-2018 | 117.9 KiB | 4,553 | 4,060 |
| vocab_test.go | H A D | 16-Nov-2018 | 33.4 KiB | 1,233 | 1,209 |
README.md
1# vocab
2
3The `vocab` package provides static types for Core and Extended types to the
4[ActivityStream Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary).
5The library is battle-tested against all 159 examples in the Vocabulary
6specification linked above in addition to unit tests.
7
8Its mission is simple: Provide meaningful static types for the ActivityStream
9Vocabulary in golang.
10
11This library is entirely code-generated by the `tools/vocab/gen` library
12and `tools/vocab` tool. Run `go generate` to refresh the library, which
13which requires `$GOPATH/bin` to be on your `$PATH`.
14
15## This library's API is huge!
16
17**The W3C does not require client applications to support all of these
18use cases.** The W3C only requires that *"all implementations must at least be
19capable of serializing and deserializing the Extended properties in accordance
20with the Activity Streams 2.0 Core Syntax,"* which what this library and the
21`activity/streams` libraries do for clients. This library's API is large to
22permit clients to use as much or as little as desired.
23
24## What it does
25
26This library is given a `map[string]interface{}`, presumably from an
27ActivityStream or JSON-LD kind of JSON, and returns a static type that provides
28a statically-typed API.
29
30For example, consider an application that receives the simple ActivityStream
31Vocabulary object in the following JSON:
32
33```golang
34{
35 "@context": "https://www.w3.org/ns/activitystreams",
36 "type": "Note",
37 "name": "Automated Train",
38 "content": "Now arriving at sector C test labs and control facilities.",
39 "published": "1998-11-08T08:47Z",
40 "actor": "http://freeman.example.org"
41}
42```
43
44In order to extract this information, the application can use `encoding/json`
45to obtain a `map[string]interface{}` of this data. It cannot use a raw direct
46type because JSON-LD, and therefore the ActivityStream Vocabulary, permit the
47same property to be any of a JSON string, a JSON object, or a JSON array in most
48conditions. Consider:
49
50* The `type`, `name`, `content`, and `actor` properties could be a single value
51 or a JSON array, resulting in JSON deserializing to an `interface{}` or
52 `[]interface{}` for these properties
53* Any of these properties could be a string value or need to be treated as an
54 [IRI](https://www.ietf.org/rfc/rfc3987.txt)
55* The `published` time conforms to RFC3339 with the exception that seconds may
56 be omitted
57
58Therefore, trying to statically determine this with typical JSON tagging does
59not work:
60
61```golang
62type NaiveActivity struct {
63 type string `json:"Type"` // Not OK, cannot handle array of strings
64 name []string `json:"Name"` // Not OK, cannot handle single values
65 // ...
66 published time.Time `...` // Not OK, cannot handle when seconds are omitted
67}
68```
69
70This is the motivation for this library.
71
72All of these considerations are presented as:
73
74```golang
75type Note struct { ... }
76func (n *Note) NameLen() int { ... }
77func (n *Note) IsNameString(index int) bool { ... }
78func (n *Note) IsNameIRI(index int) bool { ... }
79func (n *Note) GetNameString(index int) string { ... }
80// And so on
81```
82
83Note that the resulting API and property type possibilities is *large*. This is
84a natural consequence of the specification being built on top of JSON-LD.
85
86## What it doesn't do
87
88This library does not use the `reflect` package at all. It prioritizes
89minimizing dependencies and speed over binary size.
90
91The ActivityStream specification is built on top of JSON-LD, which uses JSON.
92This library should be used with `encoding/json` in order to transform a raw
93string to a `map[string]interface{}` and then to these static types.
94
95This library does not set the `"@context"` property required when sending
96serialized data. Clients are in charge of setting it to
97`"https://www.w3.org/ns/activitystreams"`.
98
99This implementation is heavily opinionated against understanding JSON-LD due to
100its sacrifice of semantic meaning, significant increase of complexity, even
101weaker typing, and increased exposure to partially-understood messages. These
102costs earn a degree of flexibility that is not needed for the ActivityStream
103Vocabulary.
104
105This library is *not* a [JSON-LD](https://json-ld.org/) parser, and by design
106does not implement any further understanding of JSON-LD that may be outlined in
107the [W3C's JSON-LD](https://www.w3.org/TR/json-ld/) specification. Furthermore,
108it does *not* implement any of the JSON-LD
109[processing algorithms](https://www.w3.org/TR/json-ld-api/). If this
110functionality is strictly needed, or this library is not suitable, please see
111[piprate/json-gold/ld](https://github.com/piprate/json-gold) and its
112[documentation](https://godoc.org/github.com/piprate/json-gold/ld).
113
114## Other considerations
115
116This library is entirely code-generated. Determined clients can add their own
117custom extended types to the `tools/defs` library and generate a useful type.
118However, this process is purposefully painful to force clients to seriously
119consider whether they need their own [custom type](https://xkcd.com/927).
120
121The code-generation aspect also allows the specification to be translated into
122declarative data, which permits certain kinds of validation and verification.
123This has resulted in feedback to the specification and the W3C working group.
124
125## Thanks
126
127Many thanks to those who have worked on JSON-LD, ActivityStreams Core, and the
128ActivityStreams Vocabulary specifications.
129