4. Extensions
This vocabulary may be extended in the regular way, by creating new or importing existing predicates and classes from other RDF based ontologies. Extensions may be made to any resource, including adding new objects as well as properties. If there is a property in one of the ontologies that are already included in the context, then it is RECOMMENDED to use a CURIE, the namespace and property name separated by a :
character, as the JSON-LD key rather than creating a new context.
For example, it is easier to add skos:prefLabel
to the Annotation rather than requiring clients to download a new context document to discover the mapping.
Example 97: Extension Example 1
{
"@context": "http://www.w3.org/ns/anno.jsonld",
"id": "http://example.org/anno77",
"type": "Annotation",
"skos:prefLabel": "Picture Annotation",
"body": {
"type": "TextualBody",
"value": "I love this picture!"
},
"target": {
"id": "http://example.com/images/picture1",
"type": "Image"
}
}
In order to ensure a lack of collision between key names, a JSON-LD context document SHOULD be made available when the term is not from an ontology that is already in the Web Annotation context. Extension contexts MUST NOT redefine existing JSON-LD keys from the Web Annotation context. Implementations MUST ignore unfamiliar properties when processing the data, but servers SHOULD preserve them if they are part of a valid and included context.
For example, adding height and width for images from the EXIF vocabulary [exif] could be done by defining a JSON-LD context, and including the height
and width
properties and linking to the newly defined context in the Annotation's serialization.
Example 98: Extension Example 2
{
"@context": [
"http://www.w3.org/ns/anno.jsonld",
"http://example.org/images/ns/extension.jsonld"
],
"id": "http://example.org/anno78",
"type": "Annotation",
"skos:prefLabel": "Picture Annotation",
"body": {
"type": "TextualBody",
"value": "I love this picture!"
},
"target": {
"id": "http://example.com/images/picture1",
"type": "Image",
"height": 768,
"width": 1024
}
}
Note that the current JSON-LD [JSON-LD] specification does not allow arrays to contain other arrays directly. As JSON-LD is the RECOMMENDED serialization format, extensions SHOULD avoid the use of this pattern.
A. JSON-LD Context
The RECOMMENDED serialization format is [JSON-LD]. The JSON-LD context presented below is RECOMMENDED to ensure consistency between implementations, and SHOULD be referenced as http://www.w3.org/ns/anno.jsonld
. The same URI SHOULD be used as the profile URI for representations that conform to the model and context.
{
"dc:rights": "Copyright © 2016 W3C ® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark use rules apply. This Document is licensed under the W3C Software and Document license",
"dcterms:license": { "@id": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document" },
"@context": {
"oa": "http://www.w3.org/ns/oa#",
"dc": "http://purl.org/dc/elements/1.1/",
"dcterms": "http://purl.org/dc/terms/",
"dctypes": "http://purl.org/dc/dcmitype/",
"foaf": "http://xmlns.com/foaf/0.1/",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"skos": "http://www.w3.org/2004/02/skos/core#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"iana": "http://www.iana.org/assignments/relation/",
"owl": "http://www.w3.org/2002/07/owl#",
"as": "http://www.w3.org/ns/activitystreams#",
"schema": "http://schema.org/",
"id": {"@type": "@id", "@id": "@id"},
"type": {"@type": "@id", "@id": "@type"},
"Annotation": "oa:Annotation",
"Dataset": "dctypes:Dataset",
"Image": "dctypes:StillImage",
"Video": "dctypes:MovingImage",
"Audio": "dctypes:Sound",
"Text": "dctypes:Text",
"Content": "oa:Content",
"TextualBody": "oa:TextualBody",
"ResourceSelection": "oa:ResourceSelection",
"SpecificResource": "oa:SpecificResource",
"FragmentSelector": "oa:FragmentSelector",
"CssSelector": "oa:CssSelector",
"XPathSelector": "oa:XPathSelector",
"TextQuoteSelector": "oa:TextQuoteSelector",
"TextPositionSelector": "oa:TextPositionSelector",
"DataPositionSelector": "oa:DataPositionSelector",
"SvgSelector": "oa:SvgSelector",
"RangeSelector": "oa:RangeSelector",
"TimeState": "oa:TimeState",
"HttpState": "oa:HttpRequestState",
"CssStylesheet": "oa:CssStyle",
"Choice": "oa:Choice",
"Person": "foaf:Person",
"Software": "as:Application",
"Organization": "foaf:Organization",
"AnnotationCollection": "as:OrderedCollection",
"AnnotationPage": "as:OrderedCollectionPage",
"Audience": "schema:Audience",
"Motivation": "oa:Motivation",
"bookmarking": "oa:bookmarking",
"classifying": "oa:classifying",
"commenting": "oa:commenting",
"describing": "oa:describing",
"editing": "oa:editing",
"highlighting": "oa:highlighting",
"identifying": "oa:identifying",
"linking": "oa:linking",
"moderating": "oa:moderating",
"questioning": "oa:questioning",
"replying": "oa:replying",
"reviewing": "oa:reviewing",
"tagging": "oa:tagging",
"body": {"@type": "@id", "@id": "oa:hasBody"},
"target": {"@type": "@id", "@id": "oa:hasTarget"},
"source": {"@type": "@id", "@id": "oa:hasSource"},
"selector": {"@type": "@id", "@id": "oa:hasSelector"},
"state": {"@type": "@id", "@id": "oa:hasState"},
"scope": {"@type": "@id", "@id": "oa:hasScope"},
"refinedBy": {"@type": "@id", "@id": "oa:refinedBy"},
"startSelector": {"@type": "@id", "@id": "oa:hasStartSelector"},
"endSelector": {"@type": "@id", "@id": "oa:hasEndSelector"},
"renderedVia": {"@type": "@id", "@id": "oa:renderedVia"},
"creator": {"@type": "@id", "@id": "dcterms:creator"},
"generator": {"@type": "@id", "@id": "as:generator"},
"rights": {"@type": "@id", "@id": "dcterms:rights"},
"motivation": {"@type": "@vocab", "@id": "oa:motivatedBy"},
"purpose": {"@type": "@vocab", "@id": "oa:hasPurpose"},
"homepage": {"@type": "@id", "@id": "foaf:homepage"},
"via": {"@type": "@id", "@id": "oa:via"},
"canonical": {"@type": "@id", "@id": "oa:canonical"},
"stylesheet": {"@type": "@id", "@id": "oa:styledBy"},
"cached": {"@type": "@id", "@id": "oa:cachedSource"},
"conformsTo": {"@type": "@id", "@id": "dcterms:conformsTo"},
"items": {"@type": "@id", "@id": "as:items", "@container": "@list"},
"partOf": {"@type": "@id", "@id": "as:partOf"},
"first": {"@type": "@id", "@id": "as:first"},
"last": {"@type": "@id", "@id": "as:last"},
"next": {"@type": "@id", "@id": "as:next"},
"prev": {"@type": "@id", "@id": "as:prev"},
"audience": {"@type": "@id", "@id": "schema:audience"},
"bodyText": "oa:bodyText",
"format": "dc:format",
"language": "dc:language",
"created": "dcterms:created",
"modified": "dcterms:modified",
"generated": "dcterms:issued",
"text": "oa:text",
"value": "rdf:value",
"start": "oa:start",
"end": "oa:end",
"exact": "oa:exact",
"prefix": "oa:prefix",
"suffix": "oa:suffix",
"sourceDate": "oa:sourceDate",
"sourceDateStart": "oa:sourceDateStart",
"sourceDateEnd": "oa:sourceDateEnd",
"styleClass": "oa:styleClass",
"name": "foaf:name",
"email": "foaf:mbox",
"email_sha1": "foaf:mbox_sha1sum",
"account": "foaf:nick",
"label": "rdfs:label",
"total": "as:totalItems",
"startIndex": "as:startIndex"
}
}
B. JSON-LD Frames
There is an unofficial, yet well implemented, JSON-LD specification [json-ld-framing] that describes a deterministic layout for serializing an RDF graph into a particular JSON-LD document layout. Applying the following frames to the graph of information will generate JSON as close as possible to the serialization recommended by the Web Annotation Data Model.
B.1 Annotation Frame
A Frame for serializing a single Annotation.
{
"metadata": {
"dc:rights": "Copyright © 2016 W3C ® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark use rules apply. This Document is licensed under the W3C Software and Document license",
"dcterms:license": { "@id": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document" },
},
"@context": "http://www.w3.org/ns/anno.jsonld",
"@omitDefault": true,
"type": "Annotation",
"via": {"@embed": false},
"canonical": {"@embed": false},
"rights": {"@embed": false},
"motivation": {"@embed": false},
"body": {"@embed": true},
"target": {"@embed": true},
"creator": {"@embed": true},
"generator": {"@embed": true},
"audience": {"@embed": true}
}
B.2 Annotation Collection Frame
A Frame for serializing a Collection of Annotations.
{
"metadata": {
"dc:rights": "Copyright © 2016 W3C ® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark use rules apply. This Document is licensed under the W3C Software and Document license",
"dcterms:license": { "@id": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document" },
},
"@context" : [
"http://www.w3.org/ns/anno.jsonld",
"http://www.w3.org/ns/ldp.jsonld"
],
"type": "Collection",
"first": [{"@embed": "False"}],
"last": [{"@embed": "False"}]
}
Note
If it is instead desirable to embed the first page of the Collection, change the false
for first
to true
.
B.3 Annotation Page Frame
A Frame for serializing a Page from a Collection of Annotations.
{
"metadata": {
"dc:rights": "Copyright © 2016 W3C ® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark use rules apply. This Document is licensed under the W3C Software and Document license",
"dcterms:license": { "@id": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document" },
},
"@context": "http://www.w3.org/ns/anno.jsonld",
"@omitDefault": true,
"type": "AnnotationPage",
"next": {"@embed": false},
"prev": {"@embed": false},
"partOf": {"@embed": false},
"items": {"@embed": true}
}
D. Acknowledgements
The Web Annotation Working Group gratefully acknowledges the contributions of the Open Annotation Community Group. The output of the Community Group was fundamental to the current data model.
The following people have been instrumental in providing thoughts, feedback, reviews, content, criticism and input in the creation of this specification:
Vladimir Alexiev, Art Barstow, Tim Berners-Lee, Chris Birk, Dan Brickley, Sarven Capadisli, Paolo Ciccarese, Tim Cole, Ray Denenberg, TB Dinesh, Sergiu Gordea, Benjamin Goering, Amy Guy, Ivan Herman, Frederick Hirsch, Antoine Isaac, Jacob Jett, Takeshi Kanai, Gregg Kellogg, Andreas Kuckartz, Randall Leeds, Hugo Manguinhas, Ben De Meester, Luc Moreau, Addison Phillips, Davis Salisbury, Robert Sanderson, Felix Sasaki, Doug Schepers, Tzviya Siegman, Stian Soiland-Reyes, Manu Sporney, Nick Stenning, Jon Stroop, Lutz Suhrbier, Kyrce Swenson, Raphael Troncy, Simeon Warner, Erik Wilde, Dan Whaley, Benjamin Young