This section describes the status of this document at the time of its publication. Other documents may supersede this document.
Copyright © 2012-2013 the Contributors to the IIIF, DMS Council, and other Contributors, published by the IIIF under the CC-BY license.
This document has been made available to the IIIF and DMS Council members for review, but is not endorsed by them. This is a working draft, and it is inappropriate to refer to this document other than as "work in progress".
Access to image-based resources is fundamental to many research disciplines, scholarship and the transmission of cultural knowledge. Digital images are a container for much of the information content in the Web-based delivery of images, books, newspapers, manuscripts, maps, scrolls, single sheet collections, and even digital surrogates of textiles, realia and ephemera.
This document describes how the metadata about a digitized object can be made available in a standard manner. Many different styles of viewer can be implemented that consume the information to enable a rich and dynamic experience for their users across collections and hosting institutions.
A digitized object may comprise a series of pages or surfaces; for example the pages of an edition of a newspaper, or the pages of a book together with its covers and spine.
The objective of the IIIF Metadata API is to provide the information necessary to allow a rich, online viewing environment for digitized physical objects to be presented to a user, in conjunction with the IIIF Image API. This is the sole purpose of the API, to provide easy access to the information necessary for a viewer to render an appropriate user experience for the digitized content. Therefore the information is given in a way that is human readable, but not necessarily semantically available to machines. In particular, it specifically does not aim to provide metadata that would drive discovery or user selection of the digitized objects, or machine actionable rights information. This specification is not concerned with in-document search, however that will be covered by a further document. Domain specific features, such as geo-referencing of maps to real world locations, are also covered but may be addressed in additional documents.
The following are within the scope of the current document:
The purpose of these various fields is that the relevant information is presented to the user, or may be used to support navigation. Hence these are simple text fields and do not require a rich syntax or explicit semantics. The API specifies how to transfer the information from the server to a client or viewer, but does not constrain the way in which the viewer uses that information.
The following are not within scope:
Note that in the following descriptions "[physical] object" is used to refer to the physical object that has been digitized, and "resources" refer to the digital resources that are the result of that digitization process.
There are many different types of digitized resources, from ancient scrolls to modern newspapers, from medieval manuscripts to printed books, and from large maps to small photographs. Many of them bear texts, sometimes difficult to read either due to the decay of the physical object or lack of understanding of the script or language. The following use cases are motivations for this specification.
Collectively these use cases require a model in which one can characterise the digitised resource (the Manifest), the order in which individual pages or surfaces are viewed (the Sequence), and the individual pages or surfaces (a Canvas). Each Canvas may images and/or texts associated with it (the Content) to allow the page to be viewed. A resource may also have parts; for example, a book may have chapters where several pages may be associated with a single chapter (a Range) or there may be groups of content resource above the page level, such as all of the texts that make up a single transcription of a manuscript. (a Layer).
The need for these conceptual components, shown in italics, was recognised in earlier work concerned with viewing complex digitised manuscripts. The IIIF metadata model is thus derived from this earlier work but has been extended to meet the additional practical needs when viewing and navigating of other types of digitised content. The components and their use are described in the following sections.
This specification makes use of the following primary resource types:
Each Manifest must, and is very likely to, have one Sequence, but may have more than one. Each Sequence must have one Canvas and is likely to have more than one. Each Canvas may have zero or more Content resources associated with it. Zero is unlikely, but represents the case where the page exists (or existed) but has not been digitized. This heirarchy is depicted below.
There are other types of resource including Annotation Lists, Annotations, Ranges and Layers, which are discussed later.
The following metadata fields are suggested by this specification, broken in to four sections. Each metadata field is repeatable, and most may be associated with any of the resource types:
Descriptive Metadata
The Manifest and Canvas resources must have at least one Label, even if only the position of the Canvas within the Sequence to be displayed for navigation. All other properties are optional for the different types of resource.
Rights Metadata
Rights metadata is optional for all resources.
Technical Metadata
The id and type are required for all primary resources. Height and width are required for Canvases and strongly recommended for image based content resources. Format is strongly recommended for all content resources. ViewingDirection and ViewingHint are only applicable to Sequences, and if not present then "Left-to-Right" and "paged" should be assumed.
Links to Other Resources
Links are optional for all resources. They may also have type and format associated with them.
These metadata fields and requirements are depicted in the diagram below.
Other metadata fields are possible, either custom extensions or endorsed by the IIIF. If a client discovers fields that it does not understand, then it must ignore them.
This section describes the recommended request and response patterns for the API that makes the metadata available. The REST approach is followed where a call will retrieve a description of a resource, and additional calls may be made by following links obtained from within the description. All of the requests use the HTTP GET method; creation and update of resources is not covered by this specification.
Requests
Each of the sections below recommends a URI pattern to follow for the different resources. This is not required and clients should not construct the URIs by themselves, instead they should follow links from within retrieved descriptions.
The Base URI recommended for resources made available by the API is:
{scheme}://{host}/{prefix}/{identifier}Where the parameters are:
The individual resources will have URIs below this top level pattern in the same way as the IIIF Image API, by appending a "/" and the additional information to identify the resource required. If a client requests a URI without a trailing ".json", then the server should attempt to do content-negotiation if other serializations are available, otherwise return the json representation.
Responses
The format for all responses is JSON, and the sections below describe the structure to be returned in more detail. The primary response is when the Manifest is requested and for optimization reasons this must return the Manifest, with the default Sequence, Canvases and Associations for image Content resources embedded within it. Additional Sequences and Associations are made available via additional calls.
The media type for the responses (returned in the HTTP Content-Type header value) should be "application/ld+json", but may be "application/json" and clients should process both in the same manner.
Resources may be embedded within higher level resources, or available via separate requests to URIs given in the JSON responses. These URIs are in the "@id" metadata field for the resource, and both identifier and resource type are given separate resource representations. Links to resources may either be given just as the URI if there is no additional information associated with them, or they may be a JSON object with the "@id" field. Thus the following two lines are equivalent:
{"seeAlso" : "http://www.example.org/descriptions/book1.xml"} {"seeAlso" : {"@id":"http://www.example.org/descriptions/book1.xml"}}
Each response must have a "@context" property as the very first key/value pair in the top most object. This tells Linked Data processors how to interpret the information. It must occur exactly once per response, and be omitted from any embedded resources. For example, when embedding a Sequence within a Manifest, the Sequence must not have the @context line.
Client developers should be aware that some implementations may add an "@graph" property at the top level, which contains the object. This is a side effect of JSON-LD serialization. This pattern is NOT recommended for implementation, and either the client or server can use the JSON-LD compaction algorithm to remove it.
Any additional fields beyond those defined in this specification must be mapped to RDF predicates using a Context document. In this case, the value of "@context" is an array with the first element being the IIIF context document, and the second (and subsequent) being extension Context documents. Extension contexts must not change the semantics of any of the fields defined in the IIIF context. The @context line would thus loook like:
"@context": ["http://www.shared-canvas.org/ns/context.json", "http://www.example.org/sc/contexts/extension1.json"]
Any of the descriptive, rights or linking metadata fields may be repeated. In JSON this is done by giving a list, rather than a single string. Language may also be associated with descriptive metadata strings using the following pattern of value plus the RFC 5646 code, instead of a plain string:
{"@value":"Information", "@language":"en"}Note that RFC 5646 allows the script of the text to be included after a hyphen, such as "ar-latn", and clients should be aware of this possibility.
In the examples given below, comments in the JSON are given in blue italics and must be omitted. Example information that needs to be filled out is given in green italics. The order in which the examples are presented is to allow the example to build up from the top most resource, the Manifest, down to the association of Content resources with the Canvases.
Responses should be compressed by the server as there are significant performance gains to be made for very repetitive data.
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/manifest.json
The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. It represents a single physical object and the intellectual work or works embodied within that object. In particular it includes the descriptive, rights and linking metadata for this physical object. It then references or embeds the Sequence(s) of Canvases that should be rendered to the user viewing the facsimile.
The metadata fields are included directly within the JSON object. Identifier is given the special name of "@id" and may always be dereferenced to retrieve the description of the object. After the metadata, there is then a "sequences" section, which is a list of objects. Each object is a Sequence, described in then next section and the first such Sequence should be included within the Manifest as well as being available from its own URI.
The example below includes only the Manifest level information, however it should embed the Sequence, Canvas and content information as described in the following two sections. It includes examples in the descriptive metadata for how to associate multiple entries with a single field (e.g. location) and how to be explicit about the language of a particular entry (e.g. date).
{ // Metadata about this Manifest file "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/manifest.json", "@type":"sc:Manifest", // Metadata about the physical object/intellectual work "label":"Book 1", "agent":"Anne Author (author)", "location":[ "Published: Paris, France", "Written: London, England" ], "date":[ "Circa 1400", {"@value":"Environ 1400", "@language":"fr"} ], "description":"A longer description of this example book. It should give some real information.", // Rights Metadata "license":"http://www.example.org/license.html", "attribution":"Provided by Example Organization", // Linking Metadata "service":"http://www.example.org/iiif/book1/search.html", "seeAlso":"http://www.example.org/library/catalog/book1.xml", "within":"http://www.example.org/collections/books/", // List of Sequences "sequences" : [ { "@id":"http://www.example.org/iiif/book1/sequence/normal.json", "@type":"sc:Sequence", "label":"Current Page Order" // Sequence's page order should be included here, see below... } // Any additional sequences can be referenced here... ] }
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/sequence/{name}.json
The Sequence conveys the ordering of the pages. The default sequence (and typically the only sequence) should be embedded within the Manifest, but may also be available from its own URI. Any additional sequences should be referred to from the Manifest but not embedded within it.
The new {name} parameter in the URI structure is to distinguish it from any other sequences that may be available for the physical object. Typical default names are "normal" or "basic". Names should not begin with a number, as it cannot be the first character of an XML tag making RDF/XML serialization impossible.
In the Manifest example above, the sequence is referenced by its URI and contains only the basic information of label, type and id. The default sequence should be written out in full within the Manifest file, as below.
{ // Metadata about this Sequence "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/sequence/normal.json", "@type":"sc:Sequence", "label":"Current Page Order", // The order of the Canvases "canvases": [ { "@id":"http://www.example.org/iiif/book1/canvas/p1.json", "@type":"sc:Canvas", "label":"p. 1", "height":1000, "width":750, "resources": [ // Links to the Content resources go here ... ] }, { "@id":"http://www.example.org/iiif/book1/canvas/p2.json", "@type":"sc:Canvas", "label":"p. 2", "height":1000, "width":750 }, { "@id":"http://www.example.org/iiif/book1/canvas/p3.json", "@type":"sc:Canvas", "label":"p. 3", "height":1000, "width":750 } ] }
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/canvas/{name}.json
The Canvas represents an individual page and acts as a central point for different content resources to be associated with it, or with part of it as appropriate. The {name} parameter must uniquely distinguish the canvas from all other canvases in the object. As with Sequences, the name should not begin with a number. Suggested patterns are "f1r" or "p1".
Every Canvas must have a label to display, such as "page 1", a height and a width. A Canvas is a two dimensional rectangular space with an aspect ratio that represents a single logical view of some part of the physical item, and the aspect ratio is given with the height and width properties. This allows resources to be associated with specific parts of the Canvas, rather than the entire space. It is recommended that if there is (at the time of implementation) a single image that depicts the page, then the dimensions of the image are used as the dimensions of the Canvas for simplicity. Developers must be aware that this is not always the case, such as in the examples presented, and instead scale images into the space represented by the Canvas.
The resources are included in the "resources" section of the JSON response. These may be either Annotations, used to associate the image Content resource with the Canvas, or Annotation Lists which are lists of such associations for other Content or commentary.
Canvases may be dereferenced separately from the Manifest via their URIs, and the following representation information should be returned. This information should be embedded within the Sequence file, as given in the previous section.
{ // Metadata about this Canvas "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/canvas/p1.json", "@type":"sc:Canvas", "label":"p. 1", "height":1000, "width":750, "resources": [ { "@type":"oa:Annotation" // Link from Image to Canvas should be included here, as below }, { // Reference to list of other Content resources, not included directly "@id":"http://www.example.org/iiif/book1/list/p1.json", "@type":"sc:AnnotationList" } ] }
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/annotation/{name}.json
Association of Content Resources with their respective Canvases is done via Annotations. Although normally Annotations are used for associating commentary with the thing the text is commenting on, the Open Annotation model allows any resource to be associated with any other resource, or parts thereof, and it is reused for both commentary and painting resources on the Canvas.
Annotations may also have their own URIs, conveyed by adding an "@id" property to the JSON object. The content of the Annotation should be returned if the URI is requested. Annotations are not intended in this specification to be dereferenced separately from their Annotation Lists, Sequences and Manifests, but some systems may like to do this and identifiers should be given using the recommended pattern if possible.
Each Association of a Content Resource must have the "motivation" field and the value must be "sc:painting". This is in order to distinguish it from comment annotations about the Canvas, described in further detail in section 5.6.6.
Additional features of the Open Annotation data model may also be used, such as selecting a segment of the Canvas or content resource, or embedding the comment or transcription within the Annotation. These additional advanced features are described below.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/p0001-image.json", "@type":"oa:Annotation", "motivation":"sc:painting", "resource": { "@id":"http://www.example.org/iiif/book1/res/page1.jpg", "@type":"dctypes:Image", "format":"image/jpeg", "service": { "@id":http://www.example.org/images/book1-page1/", "profile":"http://library.stanford.edu/iiif/image-api/1.1/conformance.html#level1" }, "height":2000, "width":1500 }, "on":"http://www.example.org/iiif/book1/canvas/p1.json" }
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/list/{name}.json
For some digital facsimiles, there may be more than a single image available for displaying the page. Other resources include the full text of the object, musical notations, musical performances, diagram transcriptions, higher resolution segments of part of the page, commentary annotations, tags, video, data and more. These additional resources are included in Annotation Lists, referenced from the Canvas.
The {name} parameter in the URI pattern must uniquely distinguish it from all other lists, and is typically the same name as the Canvas. As a single Canvas may have multiple lists of additional resources, perhaps divided by type, this must not be assumed however, and the URIs must be followed rather than constructed a priori. As with other uses of the {name} parameter, it should not begin with a number.
As the image is almost ubituous and required to present a meaningful rendering of the page, it is required (if possible) in the list of resources directly in the Canvas representation. The rest of the resources should be made available in a separate call. The Image annotation may also be present in this list, so care must be taken to avoid duplication.
Please note the different types and formats for the Content resources. The format should be the media type that is returned when the resource is deferenced. For resources that are displayed as part of the facsimile (such as images, text transcriptions, performances of music from the manuscript and so forth) the motivation must be "sc:painting". The type should be taken from this list in the Open Annotation specification, or a similar well-known resource type ontology.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/list/p1.json", "@type":"sc:AnnotationList", "resources": [ { "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/music.mp3", "@type":"dctypes:Sound", "format":"audio/mpeg" } "on":"http://www.example.org/iiif/book1/canvas/p1.json" }, { "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/tei-text-p1.xml", "@type":"dctypes:Text", "format":"text/xml" } "on":"http://www.example.org/iiif/book1/canvas/p1.json" }, // ... and so on ] }
It is important to be able to extract parts, or segments, of resources. In particular a very common requirement is to associate a resource with part of a Canvas, or part of an Image with either the entire Canvas or part thereof. Secondly, as transcriptions are often made available in XML files, extracting the correct page or line to associate with the Canvas or part of the Canvas is equally useful for reusing existing material.
http://www.example.com/iiif/book1/canvas/p1.json#xywh=100,100,300,50Where the four numbers are the x and y coordinates in the image or canvas, followed by the width and height. Thus this segment is 300px wide, 50px high and starts at position 100,100.
http://www.example.com/iiif/book1/res/tei.xml#xpointer(/path/to/element)
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/anno1".json, "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/tei.xml#xpointer(//line[1])" "@type":"dctypes:Text", "format":"text/xml" } "on":"http://www.example.org/iiif/book1/canvas/p1.json#xywh=100,100,500,300" }
Instead of referencing transcription text externally, it is often easier to record it in the Annotation itself. Equally, text based comments could also benefit from being included in the Annotation that associates the comment with the Canvas.
Content may be embedded instead of referenced by using the following pattern within the Annotation block:
"resource" : { "@type" : "cnt:ContextAsText", "chars" : "text here" }
If it is desirable to associate the language with the content, then it must be "language" not "@language" (otherwise the "chars" field would need to be an array with "@value").
An example of this feature:
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/p1.json", "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@type":"cnt:ContentAsText", "chars":"Here starts book one...", "format":"text/plain", "language":"en" } "on":"http://www.example.org/iiif/book1/canvas/p1.json#xywh=100,150,500,25" }
A common requirement is to have a choice between multiple images that depict the page, such as different under different lights, or taken at different times. This can be accomplished by having a "oa:Choice" object as the resource, which then refers to the options to select from. It must have one "default" and at least one further "item" to choose from. The same can be applied to a choice between other types of resources as well. This is described in the Multiplicity section of the Open Annotation specification.
The item's identifier may be "rdf:nil". This means that a valid option is not to display anything. This must NOT have a label associated with it, viewers should either use "Nothing" or an appropriate label of their choice. It may be the default option.
This may be used to model foldouts and other dynamic features of a page, by associating images of the different states with the Canvas. Depending on the nature of the images, this can be either done such that the entire image is switched to change state, or only the section of the image that has to change if the segment information is known.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/anno1.json", "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@type":"oa:Choice", "default":{ "@id":"http://www.example.org/iiif/book1/res/page1.jpg", "@type":"dctypes:Image" }, "item": [ { "@id":"http://www.example.org/iiif/book1/res/page1-blackandwhite.jpg", "@type":"dctypes:Image" } ] } "on":"http://www.example.org/iiif/book1/canvas/p1.json" }
The Scalable Vector Graphics standard (SVG) is used to describe non rectangular areas of Canvas or Image resources. The SVG document is embedded within the Annotation using the same ContentAsText approach as for embedding comments or transcriptions. If the section of an image is mapped to a Canvas, then it should be the bounding box in which the SVG viewport should be placed, rather than another SVG area. If the entire canvas is the target, then the SVG viewport is assumed to cover the entire Canvas.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/anno1.json", "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@type":"oa:SpecificResource", "full": { "@id":"http://www.example.org/iiif/book1/res/page1.jpg", "@type":"dctypes:Image" }, "selector": { "@type":["oa:SvgSelector","cnt:ContentAsText"], "chars":"<svg xmlns="..."><path d="..."/></svg>" } } "on":"http://www.example.org/iiif/book1/canvas/p1.json#xywh=100,100,300,300" }
The Cascading Style Sheets standard (CSS) is used to describe how the client should render the resource to the user. The CSS information is embedded within the Annotation using the same ContentAsText approach as for embedding comments or transcriptions. As a stylesheet may contain more than one style, and be reused between annotations, it is attached to the annotation directly in the same manner as a stylesheet being linked to an HTML document. Then the name of the style class is attached to the resource that should be styled, again in the same manner as the class attribute in html, although we use "style" to avoid confusion with object classes.
In the example below, the text should be colored red.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/anno1.json", "@type":"oa:Annotation", "motivation":"sc:painting", "stylesheet":{ "@type": ["oa:CssStyle", "cnt:ContextAsText"], "chars": ".red {color: red;}" }, "resource":{ "@type":"oa:SpecificResource", "style":"red", "full": { "@type":"cnt:ContentAsText", "chars":"Rubrics are Red, ..." } } "on":"http://www.example.org/iiif/book1/canvas/p1.json#xywh=100,150,500,30" }
CSS may also be used for rotation of images which are not correctly aligned with the Canvas. In the example below, after the image is located within the 500 wide by 30 high space within the Canvas, it is then rotated by the rendering client application around the top left corner by 45 degrees anti-clockwise.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/annotation/anno1.json", "@type":"oa:Annotation", "motivation":"sc:painting", "stylesheet":{ "@type": ["oa:CssStyle", "cnt:ContextAsText"], "chars": ".rotated {transform-origin: top left; transform: rotate(-45deg);}" }, "resource":{ "@type":"oa:SpecificResource", "style":"rotated", "full": { "@id":"http://www.example.org/iiif/book1/res/page1-detail.jpg", "@type":"dctypes:Image", } } "on":"http://www.example.org/iiif/book1/canvas/p1.json#xywh=100,150,500,30" }
For annotations which are comments about the resource, as opposed to painting content resources on to the Canvas, there are different types of Motivation to make the distinction clear. For annotations about the content (such as comments, notes, descriptions etc.) the motivation should be "oa:commenting", but may be any from the list in the Open Annotation specification.
{ "@type":"oa:Annotation", "motivation":"oa:commenting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/comment1.html", "@type":"dctypes:Text", "format":"text/html" } "on":"http://www.example.org/iiif/book1/canvas/p1.json" }
There are cases where additional information is needed to fully represent an institution's information about the structure of a work.
First, additional section information may be available as to which Canvases, or parts thereof, should be grouped together in some way. This could be for textual reasons, such as to distinguish books, chapters, verses, sections, non content bearing pages, the table of contents or similar. Equally, physical reasons might be important such as quires or gatherings, sections that have been added later and so forth. These cases are solved with Ranges.
Secondly, as the information is primarily divided by Canvas (and thus page), there may be higher level groupings of annotations that need to be recorded. For example, all of the English translation annotations of a medieval French document could be kept separate from the direct transcription, or the edition in to modern French. These cases are solved by assigning an AnnotationList to be within a Layer.
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/range/{name}.json
It may be important to describe additional structure within the text, such as newspaper articles that span pages, the range of non-content bearing pages at the beginning of a work, or chapters within a book. These are described using Ranges in a similar manner to Sequences.
A range includes one or more Canvases, or parts of Canvases. The part must be rectangular, and is given using the xywh fragment approach. This allows for selecting, for example, the areas within two newspaper pages where an article is depicted. As the information about the Canvas is already in the Sequence, it should not be repeated. In order to present a table of the different ranges to allow a user to select one, every Range must have a label. It may also have any of the other metadata fields, including especially "within" to point to another Range of which the current one is part. For example, a subsection Range could point to the section Range that it is part of.
Ranges are linked or embedded within the Manifest in a "structures" field, and have the same properties as Sequences:
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/manifest.json", "@type":"sc:Manifest", // Metadata ... "sequences": [ // Sequence etc. ... ], "structures": [ { "@id":"http://www.example.org/iiif/book1/range/r1.json", "@type":"sc:Range", "label":"Introduction", "canvases": [ "http://www.example.org/iiif/book1/canvas/p1.json", "http://www.example.org/iiif/book1/canvas/p2.json", "http://www.example.org/iiif/book1/canvas/p3.json#xywh=0,0,750,300" ] }, { "@id":"http://www.example.org/iiif/book1/range/r1-1.json", "@type":"sc:Range", "label":"Objectives and Scope", "within":"http://www.example.org/iiif/book1/range/r1.json", "canvases": ["http://www.example.org/iiif/book1/canvas/2.json#xywh=0,0,500,500"] } // And any additional ranges here ] }
Recommended URI pattern: {scheme}://{host}/{prefix}/{identifier}/layer/{name}.json
There may be groupings of annotations, such as all of the annotations that, regardless of which Canvas they target, represent a particular transcription or translation of the text in the object. In order to allow clients to maintain a coherent interface, the lists of these annotations are grouped together in Layers. Without the Layer construction, it would be impossible to determine which annotations belonged together. The client may then present a user interface that allows all of the annotations in a layer to be displayed or hidden according to the user's preference.
Each Annotation List may be part of one or more Layers, and this is recorded using the "within" relationship in the Manifest and Annotation List responses. The Layer must have a Label so that it can be presented to a user to select whether or not to view it.
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@id":"http://www.example.org/iiif/book1/list/l1.json" "@type":"sc:AnnotationList", "within": { "@id": "http://www.example.org/iiif/book1/layer/transcription.json", "@type": "sc:Layer", "label": "Diplomatic Transcription" } }
URL: http://www.example.org/iiif/book1/manifest.json
{ "@context":"http://www.shared-canvas.org/ns/context.json", "@type":"sc:Manifest", "@id":"http://www.example.org/iiif/book1/manifest.json", "label":"Book 1", "agent":"Anne Author (author)", "location":[ "Published: Paris, France", "Written: London, England" ], "date":[ "Circa 1400", {"@value":"Environ 1400", "@language":"fr"} ], "description":"A longer description of this example book. It should give some real information.", "license":"http://www.example.org/license.html", "attribution":"Provided by Example Organization", "service":"http://www.example.org/iiif/book1/search.html", "seeAlso": { "@id": "http://www.example.org/library/catalog/book1.marc", "format": "application/marc" }, "within":"http://www.example.org/collections/books/", "sequences" : [ { "@id":"http://www.example.org/iiif/book1/sequence/normal.json", "@type":"sc:Sequence", "label":"Current Page Order", "canvases": [ { "@id":"http://www.example.org/iiif/book1/canvas/p1.json", "@type":"sc:Canvas", "label":"p. 1", "height":1000, "width":750, "resources": [ { "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/page1.jpg", "@type":"dctypes:Image", "format":"image/jpeg", "service": { "@id": "http://www.example.org/images/book1-page1/", "profile":"http://library.stanford.edu/iiif/image-api/compliance.html#level0" }, "height":2000, "width":1500 }, "on":"http://www.example.org/iiif/book1/canvas/p1.json" }, { "@id":"http://www.example.org/iiif/book1/list/p1.json", "@type":"sc:AnnotationList" } ] }, { "@id":"http://www.example.org/iiif/book1/canvas/p2.json", "@type":"sc:Canvas", "label":"p. 2", "height":1000, "width":750, "resources": [ { "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/images/book1-page2/full/1500,2000/0/native.jpg", "@type":"dctypes:Image", "format":"image/jpeg", "height":2000, "width":1500, "service": { "@id":"http://www.example.org/images/book1-page2/", "profile":"http://library.stanford.edu/iiif/image-api/compliance.html#level0", "scale_factors": [1, 2, 4], "height":8000, "width":6000, "tile_width":1024, "tile_height":1024 } }, "on":"http://www.example.org/iiif/book1/canvas/p2.json" }, { "@id":"http://www.example.org/iiif/book1/list/p2.json", "@type":"sc:AnnotationList" } ] }, { "@id":"http://www.example.org/iiif/book1/canvas/p3.json", "@type":"sc:Canvas", "label":"p. 3", "height":1000, "width":750, "resources": [ { "@type":"oa:Annotation", "motivation":"sc:painting", "resource":{ "@id":"http://www.example.org/iiif/book1/res/page3.jpg", "@type":"dctypes:Image", "format":"image/jpeg", "service": { "@id":"http://www.example.org/images/book1-page3/", "profile":"http://library.stanford.edu/iiif/image-api/compliance.html#level0" }, "height":2000, "width":1500 }, "on":"http://www.example.org/iiif/book1/canvas/p3.json" }, { "@id":"http://www.example.org/iiif/book1/list/p3.json", "@type":"sc:AnnotationList" } ] } ] } ], "structures": [ { "@id": "http://www.example.org/iiif/book1/range/r1.json", "@type":"sc:Range", "label":"Introduction", "canvases": [ "http://www.example.org/iiif/book1/canvas/p1.json", "http://www.example.org/iiif/book1/canvas/p2.json", "http://www.example.org/iiif/book1/canvas/p3.json#xywh=0,0,750,300" ] } ] }
Resource | URI Pattern |
---|---|
Manifest | {scheme}://{host}/{prefix}/{identifier}/manifest.json |
Sequence | {scheme}://{host}/{prefix}/{identifier}/sequence/{name}.json |
Canvas | {scheme}://{host}/{prefix}/{identifier}/canvas/{name}.json |
Content | {scheme}://{host}/{prefix}/{identifier}/res/{name}.{format} |
Annotation | {scheme}://{host}/{prefix}/{identifier}/annotation/{name}.json |
AnnotationList | {scheme}://{host}/{prefix}/{identifier}/list/{name}.json |
Range | {scheme}://{host}/{prefix}/{identifier}/range/{name}.json |
Layer | {scheme}://{host}/{prefix}/{identifier}/layer/{name}.json |
Descriptive | Rights | Technical | Linking | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
label | agent | date | location | descript. | attribut. | license | @id | @type | format | height | width | viewDir. | viewHint. | service | seeAlso | within | |
Manifest | MAN | OPT | OPT | OPT | REC | OPT | OPT | MAN | MAN | N/A | N/A | N/A | N/A | N/A | OPT | OPT | OPT |
Sequence | OPT | OPT | OPT | OPT | OPT | OPT | OPT | REC | MAN | N/A | N/A | N/A | OPT | OPT | OPT | OPT | OPT |
Canvas | MAN | OPT | OPT | OPT | OPT | OPT | OPT | MAN | MAN | N/A | MAN | MAN | N/A | N/A | OPT | OPT | OPT |
Annotation | OPT | N/A | N/A | N/A | N/A | OPT | OPT | REC | MAN | N/A | N/A | N/A | N/A | N/A | OPT | OPT | OPT |
AnnotationList | OPT | N/A | N/A | N/A | N/A | OPT | OPT | MAN | MAN | N/A | N/A | N/A | N/A | N/A | OPT | OPT | OPT |
Range | MAN | OPT | OPT | OPT | OPT | OPT | OPT | MAN | MAN | N/A | N/A | N/A | OPT | OPT | OPT | OPT | OPT |
Layer | MAN | OPT | OPT | OPT | OPT | OPT | OPT | MAN | MAN | N/A | N/A | N/A | OPT | OPT | OPT | OPT | OPT |
Image Content | OPT | N/A | N/A | N/A | N/A | OPT | OPT | MAN | MAN | REC | REC | REC | N/A | N/A | OPT | OPT | OPT |
Other Content | OPT | N/A | N/A | N/A | N/A | OPT | OPT | MAN | MAN | REC | N/A | N/A | N/A | N/A | OPT | OPT | OPT |