diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 142 |
1 files changed, 142 insertions, 0 deletions
@@ -0,0 +1,142 @@ +#+title: Namespaced Extensions Only ActivityStreams +#+author: Vivien Kraus +#+email: vivien@planete-kraus.eu +#+language: en + +* Namespaced Extensions Only ActivityStreams +ActivityStreams is cool, but json-ld is horribly complex. We believe +that it’s OK to define the NEO-ActivityStreams format by only +accepting JSON-LD that: + +- have exactly one top-level object; +- have exactly one context object; +- the context object is directly in the top-level object, at the top + of the file; +- the context is an array, a single string, or a single map; +- if an array, the first elements of the array is a list of guaranteed + non-overlapping context URIs, that do not change the meaning of the + definitions of other contexts, and that dereference to constant + definitions; +- the last element of the array is optionally a map from prefixes to + namespaces (strings ending in '#' or '/'); +- there are no two overlapping namespaced extensions. + +It is OK to expect context URIs to be immutable in all cases, because +parsing a json-ld document should yield the exact same semantics +whenever it is parsed: whether the server hosting the context is +offline, or whether its domain named has been reclaimed by a malicious +entity, for instance. If the semantics of the context change in a +backward-incompatible way, the easy solution for the context author is +to version the context document and host it in a version-dependent +URI. + +We believe that it is OK to have all these constraints because it +means server functionality can be achieved just by looking at the +pre-parsed context URIs, and client-specific extensions can be put +under a namespace. + +Client-specific extensions should NOT add any term definition in the +context. This is not idiomatic json, and is not very readable (URI +values for properties would be represented as a map with to keys, +'@value' and '@type' mapped to "@id"), however we believe noone +actually reads json-ld data, and this makes server-side processing way +easier. + +** Server-side processing of NEO-AS +Servers process the activities according to a set of semantic rules +for the data, expressed by context URIs. If an activity uses an +unknown context URI, the server assumes that it does not interfere +with the contexts it recognizes and processes the data without needing +to understand those it does not recognize. Therefore, the server never +has to fetch any context from the web. When transmitting a NEO-AS +object, the server should re-write the non-namespaced properties and +discard context URIs that it does not understand. It should also make +sure that no two namespaces use the same prefix, and transmit all the +namespaced data. This way, downstream users of the object can parse it +as full JSON-LD. + +** Client-side processing of NEO-AS +Client-side extension data should be generated under a prefix that is +not already bound in the existing data. Parsing the data should be a +2-step procedure: first, scan the context to find which prefix is +bound to the extension namespace, and then use this prefix to +dereference the object properties. Since the context object is at the +top, parsing extension data is done in one step. + +** Examples + +Here are two examples of how to convert json-ld data from the json-ld +playground to neo-as. Many of the examples use the schema.org context, +without a namespace. + +*** Person + +Here is how the Person example can put the schema.org vocabulary under +a proper namespace, in case it is expected to not be immutable. + +The source JSON-LD: + +#+begin_src js :eval no + { + "@context": "http://schema.org/", + "@type": "Person", + "name": "Jane Doe", + "jobTitle": "Professor", + "telephone": "(425) 123-4567", + "url": "http://www.janedoe.com" + } +#+end_src + +is now converted to: + +#+begin_src js :eval no + { + "@context": { "schema": "http://schema.org/" }, + "@type": "Person", + "schema:name": "Jane Doe", + "schema:jobTitle": "Professor", + "schema:telephone": "(425) 123-4567", + "schema:url": { "@value": "http://www.janedoe.com", "@type": "@id" } + } +#+end_src + +Note that the =schema:url= value starts with =http://=, so it would be +OK to not decorate it with =@value= and =@type: @id=. + +*** Event + +This example adds a term definition in the context, which we do not +want. + +#+begin_src js :eval no + { + "@context": { + "ical": "http://www.w3.org/2002/12/cal/ical#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "ical:dtstart": { + "@type": "xsd:dateTime" + } + }, + "ical:summary": "Lady Gaga Concert", + "ical:location": "New Orleans Arena, New Orleans, Louisiana, USA", + "ical:dtstart": "2011-04-09T20:00:00Z" + } +#+end_src + +It is converted to: + +#+begin_src js :eval no + { + "@context": { + "ical": "http://www.w3.org/2002/12/cal/ical#", + "xsd": "http://www.w3.org/2001/XMLSchema#" + }, + "ical:summary": "Lady Gaga Concert", + "ical:location": "New Orleans Arena, New Orleans, Louisiana, USA", + "ical:dtstart": { "@value": "2011-04-09T20:00:00Z", "@type": "xsd:dateTime" } + } +#+end_src + +# Local Variables: +# mode: org +# End: |