diff --git a/source/_includes/links.md b/source/_includes/links.md index 75c8d5359..1cd1f66e8 100644 --- a/source/_includes/links.md +++ b/source/_includes/links.md @@ -245,6 +245,7 @@ [prezi3-considerations]: {{ site.api_url | absolute_url }}/presentation/3.{{ site.data.apis.presentation.latest.minor }}/#4-json-ld-considerations "Presentation API Section 4" [prezi3-html]: {{ site.api_url | absolute_url }}/presentation/3.{{ site.data.apis.presentation.latest.minor }}/#45-html-markup-in-property-values "Presentation API Section 4.4" [prezi3-languages]: {{ site.api_url | absolute_url }}/presentation/{{site.data.apis.presentation.latest.major}}.{{ site.data.apis.presentation.latest.minor }}/#language-of-property-values "Language of Property Values" +[prezi40-languages]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#language-of-property-values "Language of Property Values" [prezi3-ldce]: {{ site.api_url | absolute_url }}/presentation/3.{{ site.data.apis.presentation.latest.minor }}/#linked-data-context-and-extensions "Linked Data Context and Extensions" [prezi3-provider]: {{ site.api_url | absolute_url }}/presentation/3.{{ site.data.apis.presentation.latest.minor }}/#provider [prezi3-service]: {{ site.api_url | absolute_url }}/presentation/3.{{ site.data.apis.presentation.latest.minor }}/#service @@ -287,6 +288,7 @@ [registry-selectors]: {{ site.api_url | absolute_url }}/registry/selectors/ [registry-services]: {{ site.api_url | absolute_url }}/registry/services/ [registry-profiles]: {{ site.api_url | absolute_url }}/registry/profiles/ +[registry-rights]: {{ site.api_url | absolute_url }}/registry/rights/ [registry-timeModes]: {{ site.api_url | absolute_url }}/registry/timeModes/ [registry-types]: {{ site.api_url | absolute_url }}/registry/types/ [registry-viewingDirections]: {{ site.api_url | absolute_url }}/registry/viewingDirections/ @@ -328,6 +330,7 @@ [prezi-40-model-PerspectiveCamera]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#PerspectiveCamera [prezi-40-model-PointAudio]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#PointAudio [prezi-40-model-PointSelector]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#PointSelector +[prezi-40-model-Quantity]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#Quantity [prezi-40-model-Range]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#Range [prezi-40-model-RotateTransform]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#RotateTransform [prezi-40-model-ScaleTransform]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#ScaleTransform @@ -350,8 +353,10 @@ [prezi-40-model-body]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#body [prezi-40-model-color]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#color [prezi-40-model-duration]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#duration +[prezi-40-model-environment-map]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#environmentMap [prezi-40-model-exclude]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#exclude [prezi-40-model-far]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#far +[prezi-40-model-fileSize]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#fileSize [prezi-40-model-fieldOfView]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#fieldOfView [prezi-40-model-format]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#format [prezi-40-model-height]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#height @@ -363,12 +368,14 @@ [prezi-40-model-items]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#items [prezi-40-model-label]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#label [prezi-40-model-language]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#language +[prezi-40-model-list]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#List [prezi-40-model-lookAt]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#lookAt [prezi-40-model-metadata]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#metadata [prezi-40-model-motivation]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#motivation [prezi-40-model-navDate]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#navDate [prezi-40-model-navPlace]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#navPlace [prezi-40-model-near]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#near +[prezi-40-model-partOf]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#partOf [prezi-40-model-placeholderContainer]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#placeholderContainer [prezi-40-model-position]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#position [prezi-40-model-profile]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#profile @@ -378,6 +385,7 @@ [prezi-40-model-rendering]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#rendering [prezi-40-model-requiredStatement]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#requiredStatement [prezi-40-model-rights]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#rights +[prezi-40-model-seeAlso]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#seeAlso [prezi-40-model-service]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#service [prezi-40-model-source]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#source [prezi-40-model-spatialScale]: {{ site.api_url | absolute_url }}/presentation/4.0/model/#spatialScale diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 34c142fca..b6b7c6063 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -151,11 +151,7 @@ This document acts as an introduction to the specification through a set of typi 8. **Comment on Feature of a Painting** - a Manifest that represents a painting and a comment highlighting a particular region of the painting. 9. **Interactive 3D Light Switch** - a Manifest that represents a Scene containing a light and a 3D model of a light switch, where a user can click or otherwise interact with the switch to turn the light on and off. -These use case were chosen as a broad sample to introduce IIIF concepts. Many more use cases are provided as recipes in the [IIIF Cookbook](link). - - -> TODO Consider diagrams - +These use cases were chosen as a broad sample to introduce IIIF concepts. Many more use cases are provided as recipes in the [IIIF Cookbook][annex-cookbook]. # Foundations @@ -174,7 +170,7 @@ The Manifest's [`items`][prezi-40-model-items] property is an ordered list of _C Manifests have descriptive, technical and linking properties. The required properties of Manifests are [`id`][prezi-40-model-id], [`type`][prezi-40-model-type], [`items`][prezi-40-model-items] and [`label`][prezi-40-model-label]. Other commonly used properties include [`summary`][prezi-40-model-summary], [`metadata`][prezi-40-model-metadata], [`rights`][prezi-40-model-rights], [`thumbnail`][prezi-40-model-thumbnail], [`homepage`][prezi-40-model-homepage] and [`provider`][prezi-40-model-provider]. -(๐Ÿ‘€) [Model Documentation](model/#manifest) +(๐Ÿ‘€) [Model Documentation](model/#Manifest) ```jsonc @@ -288,13 +284,13 @@ Scenes may also have the [`duration`][prezi-40-model-duration] property in the s Scenes can have time-based and image content in them as well as 3D content. See model for how to do this. -[๐Ÿ‘€ Model Documentation](model/#containers) +[๐Ÿ‘€ Model Documentation](model/#Containers) ## Annotations -IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. +IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-w3c-webanno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. In each of the three Containers above, an **Annotation** links the Container to a Content Resource. The Content Resource in the [`body`][prezi-40-model-body] property is _painted_ into the Container by an Annotation whose [`target`][prezi-40-model-target] property is the [`id`][prezi-40-model-id] of the Container. In all three simple cases here the [`target`][prezi-40-model-target] property is the [`id`][prezi-40-model-id] of the Container with no further qualification. @@ -425,7 +421,6 @@ Collections may include both other Collections and Manifests, forming a tree-str } ``` -:eyes: ### Range @@ -465,7 +460,6 @@ Ranges may include Containers, parts of Containers via Specific Resources or fra } ``` -:eyes: @@ -475,7 +469,7 @@ Ranges may include Containers, parts of Containers via Specific Resources or fra This example is a Manifest with one Canvas, representing an artwork. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. -The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional---the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image.The [`target`][prezi-40-model-target] property of the Annotation is the Canvas [`id`][prezi-40-model-id], unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. +The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional---the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The [`target`][prezi-40-model-target] property of the Annotation is the Canvas [`id`][prezi-40-model-id], unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. The example demonstrates the use of the common descriptive properties [`label`][prezi-40-model-label] for the title of the artwork, [`metadata`][prezi-40-model-metadata] for additional information to display to the user, [`summary`][prezi-40-model-summary] for a brief description of the artwork, [`rights`][prezi-40-model-rights] to assert a rights statement or license from a controlled vocabulary, [`homepage`][prezi-40-model-homepage] to link to the artwork's specific web page, [`thumbnail`][prezi-40-model-thumbnail] to provide a small image to stand for the Manifest, [`provider`][prezi-40-model-provider] to give information about the publisher of the Manifest, and finally, [`service`][prezi-40-model-service] to specify a IIIF Image API service that provides features such as deep zooming, derivative generation, image fragment referencing, rotation, and more. @@ -591,7 +585,7 @@ The example demonstrates the use of the common descriptive properties [`label`][ * The Painting Annotation is a member of the [`items`][prezi-40-model-items] property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. * The [`metadata`][prezi-40-model-metadata] label and value pairs are for display to the user rather than for machines to interpret. * The [`rights`][prezi-40-model-rights] property is always a single string value which is a URI. -* Any resource can have a [`provider`][prezi-40-model-provider] property which a client can display to the user. This typically tells the user who the publisher is and how they might be contacted. The value of this property is an [Agent](model/#agent). +* Any resource can have a [`provider`][prezi-40-model-provider] property which a client can display to the user. This typically tells the user who the publisher is and how they might be contacted. The value of this property is an [Agent](model/#Agent). * The [`service`][prezi-40-model-service] property specifies a software application that a client might interact with to gain additional information or functionality, in this case, the IIIF Image API. Images in IIIF do not require an Image Service---we have included one here as an example, but do not include a service in the following image examples for brevity. {: .note} @@ -605,7 +599,7 @@ Properties: [id][prezi-40-model-id], [type][prezi-40-model-type], [label][prezi- ## Use Case 2: Book -This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the [`behavior`][prezi-40-model-behavior] property to indicate to a client that the object is _paged_---this helps a client generate the correct user experience. The [`viewingDirection`][prezi-40-model-viewingDirection] property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a [`rendering`][prezi-40-model-rendering] property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The [`start`][prezi-40-model-start] property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The [`requiredStatement`][prezi-40-model-requiredStatement] is a message that a client MUST show to the user when presenting the Manifest. +This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the [`behavior`][prezi-40-model-behavior] property to indicate to a client that the object is _paged_---this helps a client generate the correct user experience. The [`viewingDirection`][prezi-40-model-viewingDirection] property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a [`rendering`][prezi-40-model-rendering] property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The [`start`][prezi-40-model-start] property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The [`requiredStatement`][prezi-40-model-requiredStatement] is a message that a client _MUST_ show to the user when presenting the Manifest. ```json { @@ -749,7 +743,7 @@ Properties: [behavior][prezi-40-model-behavior], [viewingDirection][prezi-40-mod ## Use Case 3: Periodical -This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a run of the _The Tombstone Epitaph_, published from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. The parent Collection and each of its child Collections use the [`behavior`][prezi-40-model-behavior] "multi-part" to signal that the Collections and their Manifests are part of a logical set. Each of the year Collections has one Manifest for each issue of the newspaper. +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a run of _The Tombstone Epitaph_, published from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. The parent Collection and each of its child Collections use the [`behavior`][prezi-40-model-behavior] "multi-part" to signal that the Collections and their Manifests are part of a logical set. Each of the year Collections has one Manifest for each issue of the newspaper. The top-level Collection has a [`navPlace`][prezi-40-model-navPlace] property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each Manifest has a [`navDate`][prezi-40-model-navDate] property that could be used to plot the issues on a timeline or calendar-style user interface. Within each Manifest, the [`structures`][prezi-40-model-structures] property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within those sections, which may be spread across multiple columns and pages. Each story's Range includes the [`supplementary`][prezi-40-model-supplementary] property to link to an Annotation Collection that provides the text of the story. @@ -928,10 +922,6 @@ Classes: [Collection][prezi-40-model-Collection], [Range][prezi-40-model-Range], Properties: [behavior][prezi-40-model-behavior], [navPlace][prezi-40-model-navPlace], [navDate][prezi-40-model-navDate], [structure][prezi-40-model-structures], [supplementary][prezi-40-model-supplementary] {: .note} -thumbnail-nav -sequence - - # Audio and Video @@ -945,7 +935,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "@context": "http://iiif.io/api/presentation/4/context.json", "id": "https://example.org/iiif/presentation/examples/manifest-with-audio.json", "type": "Manifest", - "label": { "en": ["Use case 3: 45 single with 2 tracks"] }, + "label": { "en": ["Use case 4: 45 single with 2 tracks"] }, "behavior": ["auto-advance"], "accompanyingContainer": { "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/c1", @@ -1055,7 +1045,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora ```json { - "@context": "http://iiif.io/api/presentation/3/context.json", + "@context": "http://iiif.io/api/presentation/4/context.json", "id": "https://example.org/iiif/presentation/examples/external-anno.json", "type": "AnnotationPage", "items": [ @@ -1103,7 +1093,7 @@ This example is a Manifest with one Canvas that represents the temporal extent o "@context": "http://iiif.io/api/presentation/4/context.json", "id": "https://example.org/iiif/presentation/examples/manifest-with-movie.json", "type": "Manifest", - "label": { "en": ["Use Case 4: Movie with Subtitles"] }, + "label": { "en": ["Use Case 5: Movie with Subtitles"] }, "items": [ { "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/canvas", @@ -1231,7 +1221,7 @@ This example is a Manifest with one Canvas that represents the temporal extent o __Definitions__
Classes: [Manifest][prezi-40-model-Manifest], [Canvas][prezi-40-model-Canvas], [Choice][prezi-40-model-Choice]

-Properties: [fileSize](#model/fileSize), [format][prezi-40-model-format], [provides][prezi-40-model-provides], [timeMode][prezi-40-model-timeMode], [behavior][prezi-40-model-behavior], [placeholderContainer][prezi-40-model-placeholderContainer] +Properties: [fileSize](model/#fileSize), [format][prezi-40-model-format], [provides][prezi-40-model-provides], [timeMode][prezi-40-model-timeMode], [behavior][prezi-40-model-behavior], [placeholderContainer][prezi-40-model-placeholderContainer] {: .note} # 3D @@ -1254,7 +1244,7 @@ Constructs from the domain of 3D graphics are expressed in IIIF as Resources. Th A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. -There are two types of Camera, [`PerspectiveCamera`][prezi-40-model-PerspectiveCamera] and [`OrthographicCamera`][prezi-40-model-OrthographicCamera]. The first Camera defined and not [hidden](model#value-hidden) in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client provides a default Camera. The type, properties and position of this default camera are client-dependent. +There are two types of Camera, [`PerspectiveCamera`][prezi-40-model-PerspectiveCamera] and [`OrthographicCamera`][prezi-40-model-OrthographicCamera]. The first Camera defined and not [hidden](model/#value-hidden) in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client provides a default Camera. The type, properties and position of this default camera are client-dependent. ### Lights @@ -1332,7 +1322,7 @@ This example is a Manifest with a single Scene, with a single 3D model of a spac This example adds a Light and a Camera to the previous example, and places the model at a specific point rather than at the default origin position. -Annotations may use a type of Selector called a [`PointSelector`][prezi-40-model-PointSelector] to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, [`x`][prezi-40-model-x], [`y`][prezi-40-model-y] and [`z`][prezi-40-model-z] which give the value on that axis. They also have a temporal property [`instant`][prezi-40-model-instant] which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). +Annotations may use a type of Selector called a [`PointSelector`][prezi-40-model-PointSelector] to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, [`x`][prezi-40-model-x], [`y`][prezi-40-model-y] and [`z`][prezi-40-model-z] which give the value on that axis. They also have a temporal property [`instant`][prezi-40-model-instant] which can be used if the Scene has a duration. The final commenting annotation in the [Audio in 3D](#audio-in-3d) section has an example of this property. The Light is green and has a position, but has its default orientation of looking along the negative-y axis as no rotation has been specified. The Camera has a position and is pointing at the model's origin via the [`lookAt`][prezi-40-model-lookAt] property. The Camera has a [`fieldOfView`][prezi-40-model-fieldOfView] of 50. The [`near`][prezi-40-model-near] and [`far`][prezi-40-model-far] properties are included to ensure the model falls within the camera's range (although unnecessary in a simple Scene like this). The Scene has a background color. @@ -1464,8 +1454,8 @@ The Light is green and has a position, but has its default orientation of lookin {: .note} __Definitions__
-Classes: [Manifest][prezi-40-model-Manifest], [Scene][prezi-40-model-Scene], [Model](#model/Model), [SpecificResource][prezi-40-model-SpecificResource], [PointSelector][prezi-40-model-PointSelector], [PerspectiveCamera][prezi-40-model-PerspectiveCamera], [SpotLight][prezi-40-model-SpotLight]

-Properties: [backgroundColor][prezi-40-model-backgroundColor], [lookAt][prezi-40-model-lookAt], [near][prezi-40-model-near], [far][prezi-40-model-far], [feildOfView][prezi-40-model-fieldOfView], [angle][prezi-40-model-angle], [color][prezi-40-model-color] +Classes: [Manifest][prezi-40-model-Manifest], [Scene][prezi-40-model-Scene], [SpecificResource][prezi-40-model-SpecificResource], [PointSelector][prezi-40-model-PointSelector], [PerspectiveCamera][prezi-40-model-PerspectiveCamera], [SpotLight][prezi-40-model-SpotLight]

+Properties: [backgroundColor][prezi-40-model-backgroundColor], [lookAt][prezi-40-model-lookAt], [near][prezi-40-model-near], [far][prezi-40-model-far], [fieldOfView][prezi-40-model-fieldOfView], [angle][prezi-40-model-angle], [color][prezi-40-model-color] {: .note} ### Multiple 3D Objects with Transforms @@ -1642,7 +1632,7 @@ This example is a Manifest with a single Scene with multiple models painted into {: .note} __Definitions__
-Classes: [Manifest][prezi-40-model-Manifest], [Scene][prezi-40-model-Scene], [Model](#model/Model), [SpecificResource][prezi-40-model-SpecificResource], [PointSelector][prezi-40-model-PointSelector], [RotateTransform][prezi-40-model-RotateTransform], [TranslateTransform][prezi-40-model-TranslateTransform], [ScaleTransform][prezi-40-model-ScaleTransform]

+Classes: [Manifest][prezi-40-model-Manifest], [Scene][prezi-40-model-Scene], [SpecificResource][prezi-40-model-SpecificResource], [PointSelector][prezi-40-model-PointSelector], [RotateTransform][prezi-40-model-RotateTransform], [TranslateTransform][prezi-40-model-TranslateTransform], [ScaleTransform][prezi-40-model-ScaleTransform]

Properties: [exclude][prezi-40-model-exclude], [interactionMode][prezi-40-model-interactionMode] {: .note} @@ -1664,7 +1654,7 @@ A content resource may be annotated into a Scene for a period of time by use of An Annotation may target a specific point in time using a PointSelector's [`instant`][prezi-40-model-instant] property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. In this example this is used for a comment Annotation. -In this example, the audio content resources have durations that do not match the Scene's duration. The Annotation property [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) is used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. +In this example, the audio content resources have durations that do not match the Scene's duration. The [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) is used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. ```jsonc { @@ -1975,9 +1965,9 @@ A Timeline, Canvas, or Scene with [`duration`][prezi-40-model-duration] can only Painting nested content into a Scene has some special requirements that must be observed due to important distinctions relating to the infinite boundless 3D space described by a Scene. 2D image or video content resources can be painted into a Scene by first painting the image or video content resource on a Canvas and then painting the Canvas into the Scene. In the case of painting a Timeline into a Scene, an Audio Emitter can be painted into the scene where Timeline is the [`body`][prezi-40-model-body] of the Audio Emitter. This provides greater control over the intended presentation of the Timeline's audio content within the 3D space of the Scene. -A Canvas can be painted into a Scene as an Annotation, though differences between the 2D space described by a Canvas and the 3D space described by a Scene must be considered. A Canvas describes a bounded 2D space with finite [`height`][prezi-40-model-height] and [`width`][prezi-40-model-width] measured in 2D integer coordinates with a coordinate origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of 3D continuous coordinates and a coordinate origin at the center of the space. Further, although 2D images or videos with pixel height and width can be painted into a Canvas, Canvas 2D coordinates are not equivalent to pixels. An image of any height and width in pixels can be painted into a Canvas with different height and weight in coordinate units, and this has important consequences for painting Canvases into Scenes. +A Canvas can be painted into a Scene as an Annotation, though differences between the 2D space described by a Canvas and the 3D space described by a Scene must be considered. A Canvas describes a bounded 2D space with finite [`height`][prezi-40-model-height] and [`width`][prezi-40-model-width] measured in 2D integer coordinates with a coordinate origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of 3D continuous coordinates and a coordinate origin at the center of the space. Further, although 2D images or videos with pixel height and width can be painted into a Canvas, Canvas 2D coordinates are not equivalent to pixels. An image of any height and width in pixels can be painted into a Canvas with different height and width in coordinate units, and this has important consequences for painting Canvases into Scenes. -When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the 2D coordinate origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. +When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the 2D coordinate origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is collinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is collinear to) the negative y axis extending from the coordinate origin. The direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. The Canvas is scaled to the Scene such that the 2D coordinate dimensions correspond to 3D coordinate units - a Canvas 16 units wide and 9 units high will extend 16 coordinate units across the x axis and 9 coordinate units across the y axis. Because Canvas coordinate units and image content resource pixels are not equivalent, any image with a 16:9 aspect ratio painted on this Canvas would extend 16 coordinate units by 9 coordinate units in the 3D space of the Scene, whether it was 160 pixels wide and 90 pixels high or 16,000 pixels wide and 9,000 pixels high. This provides one way to control the size of a Canvas painted into a Scene. @@ -2045,7 +2035,7 @@ A [`PointSelector`][prezi-40-model-PointSelector] can be used to modify the poin Like Timelines or Canvases, Scenes can be painted into Scenes. As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through [Transforms](#transforms). -When a Scene is nested into another Scene, the [`backgroundColor`][prezi-40-model-backgroundColor] of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. +When a Scene is nested into another Scene, the [`backgroundColor`][prezi-40-model-backgroundColor] of the Scene to be nested should be ignored as it would have no meaningful effect. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. ```jsonc { @@ -2228,7 +2218,7 @@ In some cases it is desirable to influence the client's positioning of the comme "@context": "http://iiif.io/api/presentation/4/context.json", "id": "https://example.org/iiif/manifest/commenting/manifest/3", "type": "Manifest", - "label": { "en": ["1st Centry Roman portrait bust with comment"] }, + "label": { "en": ["1st Century Roman portrait bust with comment"] }, "items": [ { "id": "https://example.org/iiif/scene/commenting/scene3", @@ -2243,11 +2233,11 @@ In some cases it is desirable to influence the client's positioning of the comme "type": "Annotation", "motivation": ["painting"] , "label": { - "en": ["A 1st century Roman portait bust."] + "en": ["A 1st century Roman portrait bust."] }, "body": { - "id": "https://example.org/iiif/scene/commenting/models/portait.gltf", + "id": "https://example.org/iiif/scene/commenting/models/portrait.gltf", "type": "Model" }, "target": { @@ -2799,7 +2789,7 @@ In a storytelling or exhibition scenario, the non-painting [`annotations`][prezi All the annotations referred to by the activating annotations' [`target`][prezi-40-model-target] and [`body`][prezi-40-model-body] properties are already present in the Scene from the beginning. Initially, many of them may have the behavior `hidden`, invisible until activated. -Interactive examples are provided as recipes in the [IIIF Cookbook](link). +Interactive examples are provided as recipes in the [IIIF Cookbook][annex-cookbook]. #### The `sequence` behavior @@ -2814,7 +2804,7 @@ In many cases, the dimensions of a Canvas, or the pixel density of a photograph, The [`spatialScale`][prezi-40-model-spatialScale] property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. -The value of [`spatialScale`][prezi-40-model-spatialScale] is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., meters, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to meters for use in [`spatialScale`][prezi-40-model-spatialScale]. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a [`metadata`][prezi-40-model-metadata] field for context. +The value of [`spatialScale`][prezi-40-model-spatialScale] is a [`Quantity`][prezi-40-model-Quantity] that has a unit of length for its `unit` property. This specification defines only one length unit, "m", i.e., meters, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to meters for use in [`spatialScale`][prezi-40-model-spatialScale]. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a [`metadata`][prezi-40-model-metadata] field for context. The Presentation API also offers a corresponding [`temporalScale`][prezi-40-model-temporalScale] property for the [`duration`][prezi-40-model-duration] dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. @@ -2828,7 +2818,7 @@ While a IIIF Manifest carries the information required to present a resource on ## Linked resources -In the following example, the Manifest represents an artwork. The Manifest links to a catalogue record via the [`seeAlso`](prezi-40-model-seeAlso) property, which is intended for machine-readable resources. The [`homepage`](prezi-40-model-homepage) property links to the museum's web page about the painting, and is intended for humans. A viewer displays the latter link for the user to click on, but is unlikely to display the former (the user would just see the JSON at the other end). +In the following example, the Manifest represents an artwork. The Manifest links to a catalogue record via the [`seeAlso`][prezi-40-model-seeAlso] property, which is intended for machine-readable resources. The [`homepage`][prezi-40-model-homepage] property links to the museum's web page about the painting, and is intended for humans. A viewer displays the latter link for the user to click on, but is unlikely to display the former (the user would just see the JSON at the other end). ``` artwork with seeAlso, rendering, partOf (link to ../c19-french-painting or something) @@ -2836,11 +2826,11 @@ artwork with seeAlso, rendering, partOf (link to ../c19-french-painting or somet (maybe the seeAlso is to a linked art description) ``` -There is one Canvas, and it has a [`rendering`](prezi-40-model-rendering) property linking to a single high resolution tiff file. This link is for human consumers and would typically be displayed as a download option. +There is one Canvas, and it has a [`rendering`][prezi-40-model-rendering] property linking to a single high resolution tiff file. This link is for human consumers and would typically be displayed as a download option. -The Manifest also has a [`partOf`](prezi-40-model-partOf) property that links to several IIIF Collections that contain a reference to it in their `items` properties. The [`partOf`](prezi-40-model-partOf) property allows a Manifest to assert its place in any hierarchical relationship, such as an archival description, or a volume of a periodical, allowing the user (or machines) to navigate "up" the hierarchy and explore further. +The Manifest also has a [`partOf`][prezi-40-model-partOf] property that links to several IIIF Collections that contain a reference to it in their `items` properties. The [`partOf`][prezi-40-model-partOf] property allows a Manifest to assert its place in any hierarchical relationship, such as an archival description, or a volume of a periodical, allowing the user (or machines) to navigate "up" the hierarchy and explore further. -Another common use of [`rendering`](prezi-40-model-rendering) is at the Manifest level, to download a single resource that represents the entire Manifest. For example, the Manifest for a 100-page printed book has 100 canvases, which generate a paged user experience in a viewer. The publisher also links to a PDF representation, a plain text representation, and an ePub representation via the `rendering` property - all representations that a user could download and use offline. Each Canvas could also link to a single text file of the text of that page. +Another common use of [`rendering`][prezi-40-model-rendering] is at the Manifest level, to download a single resource that represents the entire Manifest. For example, the Manifest for a 100-page printed book has 100 canvases, which generate a paged user experience in a viewer. The publisher also links to a PDF representation, a plain text representation, and an ePub representation via the `rendering` property - all representations that a user could download and use offline. Each Canvas could also link to a single text file of the text of that page. ```jsonc { @@ -2875,19 +2865,19 @@ Another common use of [`rendering`](prezi-40-model-rendering) is at the Manifest } ``` -This example also shows how the [`fileSize`](prezi-40-model-fileSize) property can give useful information to a user when deciding what they want to download. +This example also shows how the [`fileSize`][prezi-40-model-fileSize] property can give useful information to a user when deciding what they want to download. ## Services -In many of the examples in this specification an image resource has an associated [IIIF Image API][image-api] Service. This is the most common use of [`service`](prezi-40-model-service) in IIIF, but other types of service are defined by IIIF specifications or available as extensions. Rather than just offer the link for download, the client is expected to interact with the service on the user's behalf. For the Image API, this usually means generating multiple requests for image tiles at the appropriate zoom level. For the [IIIF Search API][search-api], this means accepting user query terms, sending them to the search service endpoint, and rendering the results for further interaction (typically navigation to the result location within the Manifest). +In many of the examples in this specification an image resource has an associated [IIIF Image API][image-api] Service. This is the most common use of [`service`][prezi-40-model-service] in IIIF, but other types of service are defined by IIIF specifications or available as extensions. Rather than just offer the link for download, the client is expected to interact with the service on the user's behalf. For the Image API, this usually means generating multiple requests for image tiles at the appropriate zoom level. For the [IIIF Search API][search-api], this means accepting user query terms, sending them to the search service endpoint, and rendering the results for further interaction (typically navigation to the result location within the Manifest). -Further IIIF Services are provided by the [IIIF Authorization Flow API](auth-api), which provides endpoints for a client to learn about a user's current access to a resource, and guide them through the publisher's access control arrangements if they do not have permission, so that they can (if authorised) acquire whatever credentials the publisher requires. +Further IIIF Services are provided by the [IIIF Authorization Flow API][auth-stable-version], which provides endpoints for a client to learn about a user's current access to a resource, and guide them through the publisher's access control arrangements if they do not have permission, so that they can (if authorised) acquire whatever credentials the publisher requires. Ad hoc third party services can be developed for specific needs (with no expectation that a general-purpose IIIF client would know what to do with them). ## Content State -Links to resources and services build up a web of linked _*content*_ for human and machine consumers to interact with. The [IIIF Content State API](content-state-api) defines mechanisms for IIIF software implementations to exchange references to this content, including arbitrarily fine-grained pointers into large IIIF resources. A Content State is simply a fragment of the IIIF Presentation API, wrapped in a _Content State Annotation_, with enough information for software receiving that fragment to load it and (typically) direct the user's attention to the referenced point. A bookmark or citation could be passed between users via save and load functionality in viewers that understand Content State. +Links to resources and services build up a web of linked _*content*_ for human and machine consumers to interact with. The [IIIF Content State API][contenstate-stable-version] defines mechanisms for IIIF software implementations to exchange references to this content, including arbitrarily fine-grained pointers into large IIIF resources. A Content State is simply a fragment of the IIIF Presentation API, wrapped in a _Content State Annotation_, with enough information for software receiving that fragment to load it and (typically) direct the user's attention to the referenced point. A bookmark or citation could be passed between users via save and load functionality in viewers that understand Content State. ``` (region of a Canvas that is partOf a Manifest) @@ -2989,7 +2979,7 @@ Responses _SHOULD_ be compressed by the server as there are significant performa # Accessibility -Some IIIF resources have associated resources, such as closed-caption files for video, audio descriptions for images, or tactile graphics for visual materials, that improve access to the content for a wider range of users. These linked resources play a specific accessibility-related role relative to the resource they describe or supplement. See [A/V Use Case 5: Movie with subtitles](link to section) above. +Some IIIF resources have associated resources, such as closed-caption files for video, audio descriptions for images, or tactile graphics for visual materials, that improve access to the content for a wider range of users. These linked resources play a specific accessibility-related role relative to the resource they describe or supplement. See [A/V Use Case 5: Movie with subtitles](#use-case-5-movie-with-subtitles) above. IIIF uses the `provides` property on supplementing annotations to define the specific accessibility functionality that a linked resource enables for its target, describing why and how a client might use it rather than what the resource is by type or format. For example, a text file linked from a video might provide `closedCaptions`, or an audio file associated with a Canvas might provide an `audioDescription`. @@ -3020,13 +3010,13 @@ The value of `provides` is an array of strings, taken from the [IIIF Registry of **Key Points** * The `provides` property is placed on the annotation and not on the target of the annotation. -* The property is primarly used to define accessibility features, but can be used to define other types of functionality, such as `transcription`. +* The property is primarily used to define accessibility features, but can be used to define other types of functionality, such as `transcription`. {: .note} !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Properties: [provides](#model/provides) +Properties: [provides](model/#provides) {: .note} diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3a4a2412d..855a56aae 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -103,7 +103,7 @@ a:hover > code { ## Introduction {: #introduction} -The IIIF Presentation API is backed by a standards-based data model inspired by both earlier tree structured representations of cultural heritage objects, as well as linked data approaches with the same goal. It comprises four main types of resource: Structural (such as Collections, Manifests, and Ranges), Presentational Containers (Canvas, Scene and Timeline), Linking (Annotations), and Content (the images, texts, audio, video and models to be displayed). In addition to these, the model includes supporting classes such as Agents, and extensions to the standards for IIIF specific use cases, such as Transforms for manipulating 3d models within a Scene. +The IIIF Presentation API is backed by a standards-based data model inspired by both earlier tree structured representations of cultural heritage objects, as well as linked data approaches with the same goal. It comprises four main types of resource: Structural (such as Collections, Manifests, and Ranges), Presentational Containers (Canvas, Scene and Timeline), Linking (Annotations), and Content (the images, texts, audio, video and models to be displayed). In addition to these, the model includes supporting classes such as Agents, and extensions to the standards for IIIF specific use cases, such as Transforms for manipulating 3D models within a Scene. The Presentation API data model intentionally does not include any semantic or descriptive relationships or properties, such as the author of a book or the place where a statue was sculpted; it is solely for presenting content in a structured fashion to human users. @@ -194,7 +194,7 @@ In order to avoid HTML or script injection attacks, clients _MUST_ remove: * Tags such as `script`, `style`, `object`, `form`, `input` and similar. * All attributes other than `href` on the `a` tag, `src` and `alt` on the `img` tag. * All `href` attributes that start with the strings other than "http:", "https:", and "mailto:". - * CData sections. + * CDATA sections. * XML Comments. * Processing instructions. @@ -237,7 +237,7 @@ The value of the `@context` property _MUST_ be either the URI `http://iiif.io/ap } ``` -Any additional properties beyond those defined in this specification or the Web Annotation Data Model _SHOULD_ be mapped to RDF predicates using further context documents. These extensions _SHOULD_ be added to the top level `@context` property, and _MUST_ be added before the above context. The JSON-LD 1.1 functionality of predicate specific context definitions, known as [scoped contexts][org-w3c-json-ld-scoped-contexts], _MUST_ be used to minimize cross-extension collisions. Extensions intended for community use _SHOULD_ be [registered in the extensions registry][registry], but registration is not mandatory. +Any additional properties beyond those defined in this specification or the Web Annotation Data Model _SHOULD_ be mapped to RDF predicates using further context documents. These extensions _SHOULD_ be added to the top level `@context` property, and _MUST_ be added before the above context. The JSON-LD 1.1 functionality of predicate-specific context definitions, known as [scoped contexts][org-w3c-json-ld-scoped-contexts], _MUST_ be used to minimize cross-extension collisions. Extensions intended for community use _SHOULD_ be [registered in the extensions registry][registry], but registration is not mandatory. {% include api/code_header.html %} ``` json-doc @@ -272,7 +272,7 @@ A Collection _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be d The members of a Collection are typically listed in the `items` property or in a series of Collection Pages. The members _MUST_ be either Collections or Manifests, and _MUST NOT_ be other classes. They are listed in order within the `items` or across consecutive Collection Pages, thereby forming a hierarchy. Collections _MAY_ have no members, but this is discouraged. For example, a Collection that had its last member removed might still be valuable to maintain as an empty Collection. -If there are too many members in the collection to fit within a single document then, at the Collection publiser's discretion, the members _MAY_ be listed in Collection Pages. A reference to the first Collection Page of members is given in the `first` property, and the last page in the `last` property. In this case, the Collection _MUST NOT_ use the `items` property. Collections with pages _MUST_ have at least two pages, otherwise the members _MUST_ be included in `items` on the Collection itself. Collection Pages _MUST NOT_ be embedded within the Collection for the same reason. +If there are too many members in the collection to fit within a single document then, at the Collection publisher's discretion, the members _MAY_ be listed in Collection Pages. A reference to the first Collection Page of members is given in the `first` property, and the last page in the `last` property. In this case, the Collection _MUST NOT_ use the `items` property. Collections with pages _MUST_ have at least two pages, otherwise the members _MUST_ be included in `items` on the Collection itself. Collection Pages _MUST NOT_ be embedded within the Collection for the same reason. Member Collections _MAY_ be embedded inline within other Collections, including in Collection Pages, however Manifests _MUST NOT_ be embedded within Collections. An embedded Collection _SHOULD_ also have its own URI from which the JSON description is available. @@ -296,7 +296,7 @@ A Collection Page is an arbitrary division of members within the Collection to m A Collection Page _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the JSON description. Collection Pages _MUST NOT_ be embedded within Collections. -All Collection Pages in a Collection, with the exception of the last page, _MUST_ have the `next` property, which provides a reference to the following Collection Page. All Collection Pages in a Collection, with the exception of the first page, _MUST_ have the `prev` property, which provides a reference to the preceding Collection Page. These properties allow the navigation backwards and forwards within the overall set of pages. There is no way to jump to arbitrary positions in the sequence of pages, and clients _MUST NOT_ attempt to infer such methods from the structure of the URI of the Collection Page. Collection Pages _MUST_ have the `partOf` property, refering to the Collection of which they are part. +All Collection Pages in a Collection, with the exception of the last page, _MUST_ have the `next` property, which provides a reference to the following Collection Page. All Collection Pages in a Collection, with the exception of the first page, _MUST_ have the `prev` property, which provides a reference to the preceding Collection Page. These properties allow the navigation backwards and forwards within the overall set of pages. There is no way to jump to arbitrary positions in the sequence of pages, and clients _MUST NOT_ attempt to infer such methods from the structure of the URI of the Collection Page. Collection Pages _MUST_ have the `partOf` property, referring to the Collection of which they are part. __Properties__
A Collection Page _MUST_ have the following properties: [id](#id), [type](#type), [partOf](#partOf) and [items](#items)

@@ -314,7 +314,7 @@ A Manifest is the primary unit of distribution of IIIF and provides a descriptio Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description. -The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, which _MUST_ be embedded within the Manifest. The Containers in a single Manifest _MAY_ be of different classes. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. +The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, which _MUST_ be embedded within the Manifest. The Containers in a single Manifest _MAY_ be of different classes. The Manifest _MAY_ have a `structures` property listing one or more [Ranges](#Range) which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. __Properties__
A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items)

@@ -331,12 +331,12 @@ All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. Th Containers _SHOULD_ have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. Annotations that do not associate content to be rendered, but instead are about the Container itself, such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. A Container _MAY_ have zero annotations associated with it and still be useful, such as when the properties of the Container convey to the user that it represents a page that has not been digitized, or there is otherwise no digital content available to display. In this case the `items` property is not included. -Containers specify extents in space and/or time with one or more space or time dimensions such as `height`, `width`, or `duration`. These dimensions allow resources to be associated with specific regions of the Canvas, within the space and/or time extents provided. Content _MUST NOT_ be associated with space or time outside of the Container's dimensions, such as at coordinates below 0,0 or greater than specified height or width for a Canvas, or before 0 seconds or after the duration for a Timeline. Content resources that have dimensions which are not defined for the Container _MUST NOT_ be associated with that Container by an Annotation that has the `motivation` value "painting". For example, it is valid to use an Annotation that has the `motivation` value "painting" to associate an Image (which has only height and width) with a Canvas that has `height`, `width`, and `duration` properties, but it is an error to associate a Video resource (which has height, width and duration) with a Canvas that does not `duration`. Such a resource _MAY_ instead be referenced using the rendering property, or by Annotations that have a `motivation` value other than "painting" in the annotations property. +Containers specify extents in space and/or time with one or more space or time dimensions such as `height`, `width`, or `duration`. These dimensions allow resources to be associated with specific regions of the Canvas, within the space and/or time extents provided. Content _MUST NOT_ be associated with space or time outside of the Container's dimensions, such as at coordinates below 0,0 or greater than specified height or width for a Canvas, or before 0 seconds or after the duration for a Timeline. Content resources that have dimensions which are not defined for the Container _MUST NOT_ be associated with that Container by an Annotation that has the `motivation` value "painting". For example, it is valid to use an Annotation that has the `motivation` value "painting" to associate an Image (which has only height and width) with a Canvas that has `height`, `width`, and `duration` properties, but it is an error to associate a Video resource (which has height, width and duration) with a Canvas that does not have a `duration`. Such a resource _MAY_ instead be referenced using the rendering property, or by Annotations that have a `motivation` value other than "painting" in the annotations property. __Properties__
All Containers _MUST_ have the following properties: [id](#id) and [type](#type).

All Containers _SHOULD_ have the following properties: [label](#label), and [items](#items).

-All Containers _MAY_ have the following properites: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [canonical](#canonical), [via](#via), and [annotations](#annotations). +All Containers _MAY_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [canonical](#canonical), [via](#via), and [annotations](#annotations). {: .note} @@ -345,7 +345,7 @@ All Containers _MAY_ have the following properites: [metadata](#metadata), [summ > `"type": "Timeline"` -A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height, width and/or depth, like an image, video or 3d model. The duration of the Timeline is given in the `duration` property. +A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height, width and/or depth, like an image, video or 3D model. The duration of the Timeline is given in the `duration` property. __Properties__
A Timeline _MUST_ have the following additional properties: [duration](#duration). @@ -375,7 +375,7 @@ A Scene is a Container that represents an infinitely large three-dimensional spa The axes of the coordinate system are measured in arbitrary units. All axes use the same unit scaling and do not necessarily correspond to any physical unit of measurement, unless `spatialScale` is supplied. -All 3d resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes) local coordinate space. Transforms may modify the local coordinate space of a resource relative to the Sceneโ€™s "global" space. +All 3D resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes) local coordinate space. Transforms may modify the local coordinate space of a resource relative to the Sceneโ€™s "global" space. __Properties__
A Scene _MAY_ have the following additional properties: [duration](#duration). @@ -414,7 +414,7 @@ An Annotation _MAY_ have the following properties: [label](#label), [metadata](# > `"type": "AnnotationCollection"` -Annotation Collections allow Annotations to collected together into ordered groups. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. +Annotation Collections allow Annotations to be collected together into ordered groups. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. Annotation Collections _MUST_ have an HTTP(S) URI. The JSON-LD description _SHOULD_ be returned if the URI is dereferenced. @@ -467,7 +467,7 @@ A Textual Body is an embedded resource within an Annotation that carries, as the __Properties__
A Textual Body _MUST_ have the following properties: [type](#type), [value](#value)

-A Specific Resource _MAY_ have the following properties: [id](#id), [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+A Textual Body _MAY_ have the following properties: [id](#id), [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

{: .note} @@ -518,7 +518,7 @@ A List _MAY_ have the following properties: [id](#id), [metadata](#metadata), [s > `"type": "Independents"` -An independents is a Web Annotation construction where each of the resources independently participates in the annotation, rather than as a set. For example, if an Independents is used as the `target` of a commenting Annotation, then the body resource is about each of the entries in `items` separately, rather than the collection as a single entity. In the Web Annotation Data Model this is equivalent to having multiple independent bodies or targets listed directly in the Annotation, however this specification requires a single resource for both body and target. +An `Independents` resource is a Web Annotation construction where each of the resources independently participates in the annotation, rather than as a set. For example, if an Independents is used as the `target` of a commenting Annotation, then the body resource is about each of the entries in `items` separately, rather than the collection as a single entity. In the Web Annotation Data Model this is equivalent to having multiple independent bodies or targets listed directly in the Annotation, however this specification requires a single resource for both body and target. __Properties__
An Independents _MUST_ have the following properties: [type](#type), [items](#items)

@@ -530,28 +530,28 @@ An Independents _MAY_ have the following properties: [id](#id), [metadata](#meta ### Content Resources {: #ContentResources} -Content Resources are resources on the Web such as images, audio, video, 3d models, or text which can be associated with a Container via an Annotation, or be used with `thumbnail`, `rendering` or similar properties. +Content Resources are resources on the Web such as images, audio, video, 3D models, or text which can be associated with a Container via an Annotation, or be used with `thumbnail`, `rendering` or similar properties. -Content Resources _MUST_ have an HTTP(s) given in `id`. It _MUST_ be able to be dereferenced to retrieve the representation of the Content Resource. +Content Resources _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the representation of the Content Resource. If the Content Resource is an Image, and a IIIF Image service is available for it, then the `id` property of the Content Resource _MAY_ be a complete URI to any particular representation supported by the Image Service, such as `https://example.org/image1/full/1000,/0/default.jpg`, but _MUST NOT_ be just the URI of the Image Service. The Image _SHOULD_ have the service referenced from it using the `service` property. -If the Content Resource is a 3d Model, then regardless of the file format, it is treated as being within an infinitely large three dimensional space with an origin (0 on all three axes). This is described as its "local coordinate space". 3d Content Resources _MAY_ be painted into Scenes via a painting Annotation. When painted as an Annotation, the origin of the 3d Content Resource's local coordinate space _MUST_ be aligned with either the Scene coordinate origin by default or with a specific 3d point in the Scene if a [Point Selector](#point-selector) is used. +If the Content Resource is a 3D Model, then regardless of the file format, it is treated as being within an infinitely large three dimensional space with an origin (0 on all three axes). This is described as its "local coordinate space". 3D Content Resources _MAY_ be painted into Scenes via a painting Annotation. When painted as an Annotation, the origin of the 3D Content Resource's local coordinate space _MUST_ be aligned with either the Scene coordinate origin by default or with a specific 3D point in the Scene if a [Point Selector](#point-selector) is used. -Non-3d Content Resources such as images, audio, and video _MUST NOT_ be painted into a Scene as Annotations. Instead, to include image and video resources in a Scene, the resource(s) _MUST_ be painted on to a Canvas that is painted into the Scene. To include audio resources in a Scene, the resource(s) or Timeline _MUST_ be referenced by an AudioEmitter that is painted into the Scene. +Non-3D Content Resources such as images, audio, and video _MUST NOT_ be painted into a Scene as Annotations. Instead, to include image and video resources in a Scene, the resource(s) _MUST_ be painted on to a Canvas that is painted into the Scene. To include audio resources in a Scene, the resource(s) or Timeline _MUST_ be referenced by an AudioEmitter that is painted into the Scene. If there is a need to distinguish between Content Resources, then all such resources _SHOULD_ have the `label` property. Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. This is often described as "nesting". -A Canvas painted into a Scene has special requirements. The top-left corner of the Canvas _MUST_ be aligned with either the Scene coordinate origin by default or with a specific 3d point in the Scene if a [Point Selector](#point-selector) is used. The Canvas _MUST_ be scaled to the Scene such that Canvas coordinate dimensions after any [Transforms](#transforms) are applied correspond to Scene coordinate dimensions with 1:1 scaling. A Canvas painted into a Scene as an Annotation has forward and backward faces, and by default the forward face is toward the positive z axis of the Scene, though this may be modified by Transforms. The content of the Canvas _SHOULD_ be displayed on the forward face, and the backward face _SHOULD_ display either any `backgroundColor` of the Canvas or a reverse view of the content. +A Canvas painted into a Scene has special requirements. The top-left corner of the Canvas _MUST_ be aligned with either the Scene coordinate origin by default or with a specific 3D point in the Scene if a [Point Selector](#point-selector) is used. The Canvas _MUST_ be scaled to the Scene such that Canvas coordinate dimensions after any [Transforms](#transforms) are applied correspond to Scene coordinate dimensions with 1:1 scaling. A Canvas painted into a Scene as an Annotation has forward and backward faces, and by default the forward face is toward the positive z axis of the Scene, though this may be modified by Transforms. The content of the Canvas _SHOULD_ be displayed on the forward face, and the backward face _SHOULD_ display either any `backgroundColor` of the Canvas or a reverse view of the content. A Scene painted into a Scene has one special requirement, that any `backgroundColor` of the Scene to be painted _SHOULD_ be ignored. __Properties__
A Content Resource _MUST_ have the following properties: [id](#id) and [type](#type).

A Content Resource _SHOULD_ have the following properties: [label](#label)

-A Content Resource _MAY_ have the following properties: [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [fileSize](#fileSize),[metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [profile](#profile), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+A Content Resource _MAY_ have the following properties: [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [fileSize](#fileSize), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [profile](#profile), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

{: .note} @@ -586,7 +586,7 @@ For more information about SVG Selectors, see the [Web Annotation Data Model](ht __Properties__
An SVG Selector _MUST_ have the following properties: [type](#type) and [value](#value).

-A Fragment Selector _MAY_ have the following properties: [id](#id).

+An SVG Selector _MAY_ have the following properties: [id](#id).

{: .note} @@ -597,9 +597,9 @@ A Fragment Selector _MAY_ have the following properties: [id](#id).

There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should, equally, treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. -The spatial aspect of the point is given with `x` and `y` for a two-dimensional point, along with `z` for a three-dimentional point. The temporal aspect of the point is given with `instant`. If `instant` is not supplied, and the target resource has a `duration`, the selector is interpreted as targeting the entire duration. If `instant` is supplied, but no spatial point, the selector is interpreted as targeting the entire spatial aspect of the resource. +The spatial aspect of the point is given with `x` and `y` for a two-dimensional point, along with `z` for a three-dimensional point. The temporal aspect of the point is given with `instant`. If `instant` is not supplied, and the target resource has a `duration`, the selector is interpreted as targeting the entire duration. If `instant` is supplied, but no spatial point, the selector is interpreted as targeting the entire spatial aspect of the resource. -For 3d content resources painted into a Scene that have a local coordinate space relative to the global coordinate space of the Scene, clients _MUST_ align the local coordinate origin of the content resource with the 3d point indicated by the Point Selector within the Scene. Thus the 3d resource's origin is placed at the desired point in the Scene. For a Canvas painted into a Scene as an Annotation, the top-left corner of the Canvas (the Canvas coordinate origin) _MUST_ be aligned with the 3d point indicated by the Point Selector within the Scene. +For 3D content resources painted into a Scene that have a local coordinate space relative to the global coordinate space of the Scene, clients _MUST_ align the local coordinate origin of the content resource with the 3D point indicated by the Point Selector within the Scene. Thus the 3D resource's origin is placed at the desired point in the Scene. For a Canvas painted into a Scene as an Annotation, the top-left corner of the Canvas (the Canvas coordinate origin) _MUST_ be aligned with the 3D point indicated by the Point Selector within the Scene. __Properties__
A Point Selector _MUST_ have the following properties: [type](#type)

@@ -623,7 +623,7 @@ A Point Selector _MAY_ have the following properties: [id](#id), [x](#x), [y](#y > `"type": "WktSelector"` -Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MULTIPOLYGON. +Well-Known Text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MULTIPOLYGON. The text representation is given in the `value` property of the selector. @@ -687,7 +687,7 @@ A Visual Content Selector _MAY_ have the following properties: [id](#id) More interactive content resources, such as 3D models, may have animations or similar features that can be _activated_ by user interaction. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. The identity of the activatable aspect is given in the `value` property. __Properties__
-An Animation Selector _MUST_ have the following properties: [id](#id), [type](#type), and [value](#value). +An Animation Selector _MUST_ have the following properties: [type](#type) and [value](#value). An Animation Selector _MAY_ have the following properties: [id](#id) {: .note} @@ -705,7 +705,7 @@ An Animation Selector _MAY_ have the following properties: [id](#id) The Image API Selector is used to describe the operations expected to occur via the definitions of the IIIF Image API. This can be used with IIIF Image API services in order to retrieve a particular image representation, but also can be applied client side on static images, such as to process rotation via CSS. If an Image API Service is available, the `source` resource is the abstract image as identified by the [IIIF Image API][image-api] base URI plus identifier, and the retrieval process involves adding the correct parameters after that base URI. -The Image API Selector has properties following the parameters from the API, and record the values which would be used to fill out the URL structure in the request if a service is available. If the property is not given, then the default value for the version of the API should be used. +The Image API Selector has properties following the parameters from the API, and records the values which would be used to fill out the URL structure in the request if a service is available. If the property is not given, then the default value for the version of the API should be used. | Property | Default | Description | | -------- | --------- | ----------------------------------------------------- | @@ -714,7 +714,7 @@ The Image API Selector has properties following the parameters from the API, and | `rotation` | "0" | The string to put in the rotation parameter of the URI. Note that this must be a string in order to allow mirroring, for example "!90". | | `quality` | "default" | The string to put in the quality parameter of the URI. | | `format` | "jpg" | The string to put in the format parameter of the URI. Note that the '.' character is not part of the format, just the URI syntax. | -| `version` | "2.1" | The string representation of a published version number in "major.minor" form of the IIIF Image API. If the version given in the Selector differs from the version exposed by a Image API service, the client is expected to translate between versions as possible. | +| `version` | "2.1" | The string representation of a published version number in "major.minor" form of the IIIF Image API. If the version given in the Selector differs from the version exposed by an Image API service, the client is expected to translate between versions as possible. | __Properties__
A IIIF Image API Selector _MUST_ have the following properties: [type](#type).

@@ -737,7 +737,7 @@ A IIIF Image API Selector _MAY_ have the following properties: [id](#id), [regio Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. -Ranges _MUST_ have an HTTP(s) URI given in `id`. Top level Ranges are embedded or externally referenced within the Manifest in the `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in their `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved. +Ranges _MUST_ have an HTTP(S) URI given in `id`. Top level Ranges are embedded or externally referenced within the Manifest in the `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in their `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved. The included Containers and parts of Containers need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. @@ -835,7 +835,7 @@ All Lights _MAY_ have the following properties: [id](#id) and [label](#label). {: #AmbientLight} > `"type": "AmbientLight"` -Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. It does not have any new properties. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. +Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. It does not have any new properties. The Light itself _MUST_ be added into the Scene at a specific position, however this is only such that editing interfaces can render the object to the user. __Properties__
An Ambient Light _SHOULD_ have the following additional properties: [color](#color).

@@ -854,7 +854,7 @@ An Ambient Light _SHOULD_ have the following additional properties: [color](#col {: #DirectionalLight} > `"type": "DirectionalLight"` -Directional Lights emit their light in a specific direction as if infinitely far away, and as such the light does not come from a specific position. The rays produced are all parallel. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. +Directional Lights emit their light in a specific direction as if infinitely far away, and as such the light does not come from a specific position. The rays produced are all parallel. The Light itself _MUST_ be added into the Scene at a specific position, however this is only such that editing interfaces can render the object to the user. The light is emitted in the negative Y direction by default, thus straight down, but the orientation of the light can be altered with `lookAt` or with a `RotateTransform`. @@ -1106,7 +1106,7 @@ A Translate Transform translates or moves the resource along one or more axes. I {: #Agent} > `"type": "Agent"` -An Agent represents a person or organization, typically referenced with the `provider` property. Note that Agent is NOT an abstract class with subclasses, and thus _SHOULD_ be instantiated directly. +An Agent represents a person or organization, typically referenced with the `provider` property. Note that Agent is not an abstract class with subclasses, and thus _SHOULD_ be instantiated directly. The Agent is not intended to be used as a primary identifier for the person or organization, nor to provide structured metadata, but instead to ensure that the information to be rendered to the user can be kept together in the situation when there are multiple agents being referenced. @@ -1125,7 +1125,7 @@ An Agent _MAY_ have the following properties: [id](#id), [seeAlso](#seeAlso) and "summary": {"en": ["The IIIF Consortium is a global community of organizations and individuals working to develop and promote the International Image Interoperability Framework (IIIF)."]}, "homepage": [ { - "id": "https://iiif.io/",` + "id": "https://iiif.io/", "type": "Text", "label": {"en": ["IIIF Home Page"]}, "format": "text/html" @@ -1152,7 +1152,7 @@ An Agent _MAY_ have the following properties: [id](#id), [seeAlso](#seeAlso) and A Quantity expresses a quantity through a numerical value and associated unit of measurement. The value of `unit` _MUST_ be drawn from the list of possible units, or a registered extension. The definition of `unit` defines the [list of possible unit values](#unit). __Properties__
-A Quantity _MUST_ have the following properties: [type](#type), [quantityValue](#value), and [unit](#unit).

+A Quantity _MUST_ have the following properties: [type](#type), [quantityValue](#quantityValue), and [unit](#unit).

A Quantity _MAY_ have the following properties: [id](#id) and [label](#label). {: .note} @@ -1300,7 +1300,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the * A Collection _MAY_ have the `annotations` property with at least one item.
Clients _SHOULD_ process `annotations` on a Collection. * A Manifest _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a Manifest,. + Clients _SHOULD_ process `annotations` on a Manifest. * A Canvas _MAY_ have the `annotations` property with at least one item.
Clients _SHOULD_ process `annotations` on a Canvas. * A Range _MAY_ have the `annotations` property with at least one item.
@@ -1435,7 +1435,7 @@ The value _MUST_ be a string, and the value must be an absolute HTTP(S) URI. This property sets the color of a Light. -The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is "#FFFFFF". +The value _MUST_ be a string, which defines an RGB color. It _SHOULD_ be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is "#FFFFFF". * A Light _SHOULD_ have the `color` property
Clients _SHOULD_ render `color` on any resource type. @@ -1446,6 +1446,24 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value ``` +### conformsTo +{: #conformsTo} + +The specification that the fragment identifier in the `value` property of a `FragmentSelector` conforms to. The value allows clients to correctly interpret the fragment identifier syntax. For example, a `FragmentSelector` using the media fragments specification would have a `conformsTo` value of `http://www.w3.org/TR/media-frags/`. + +For more information about `conformsTo`, see the [Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#fragment-selector). + +The value _MUST_ be a string, and _MUST_ be an absolute URI. + +* A FragmentSelector _MAY_ have the `conformsTo` property.
+ Clients _SHOULD_ process `conformsTo` on a FragmentSelector. + +{% include api/code_header.html %} +``` json-doc +{ "conformsTo": "http://www.w3.org/TR/media-frags/" } +``` + + ### duration {: #duration} @@ -1539,8 +1557,9 @@ The value _MUST_ be a floating point number greater than 0 and less than 180, an ``` ### fileSize +{: #fileSize} -The size of a content resource in bytes. This will allow clients to determine whether the resource should be retrieved in the user's current context. For example, the same 3d Model or AV file might be available in multiple formats, and the client can choose the most appropriate one based on the `fileSize` property. +The size of a content resource in bytes. This will allow clients to determine whether the resource should be retrieved in the user's current context. For example, the same 3D Model or AV file might be available in multiple formats, and the client can choose the most appropriate one based on the `fileSize` property. The value _MUST_ be a positive integer. @@ -1689,7 +1708,7 @@ A floating point number giving the time of the point in seconds from the beginni ### intensity {: #intensity} -This property sets the strength or brightness of a Light. The `value` of the referenced Quantity indicates the desired intensity on a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). If this property is not specified, then the default intensity value is client-dependent. +This property sets the strength or brightness of a Light. The `quantityValue` of the referenced Quantity indicates the desired intensity on a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). If this property is not specified, then the default intensity value is client-dependent. The value of this property _MUST_ be a Quantity. The value of the `unit` property of the Quantity _MUST_ be `relative`. @@ -1974,7 +1993,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ Clients _MAY_ render `navDate` on a Range. * All Container types _MAY_ have the `navDate` property.
Clients _MAY_ render `navDate` on Containers. -* Annotations _MAY_ have the `navDate` property. +* Annotations _MAY_ have the `navDate` property.
Clients _MAY_ render `navDate` on Annotations. * Other types of resource _MUST NOT_ have the `navDate` property.
Clients _SHOULD_ ignore `navDate` on other types of resource. @@ -1989,7 +2008,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. -The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] containing one or more [Features] [link]. The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. +The value of the property _MUST_ be a [GeoJSON Feature Collection][link] containing one or more [Features][link]. The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. * A Collection _MAY_ have the `navPlace` property.
Clients _MAY_ render `navPlace` on a Collection. @@ -1999,7 +2018,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai Clients _MAY_ render `navPlace` on a Range. * All Container types _MAY_ have the `navPlace` property.
Clients _MAY_ render `navPlace` on Containers. -* Annotations _MAY_ have the `navPlace` property. +* Annotations _MAY_ have the `navPlace` property.
Clients _MAY_ render `navPlace` on Annotations. * Other types of resource _MUST NOT_ have the `navPlace` property.
Clients _SHOULD_ ignore `navPlace` on other types of resource. @@ -2032,7 +2051,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai ### near {: #near} -This property gives the distance along the Cameria's axis of orientation from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. +This property gives the distance along the Camera's axis of orientation from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be less than the value for `far` for the same Camera. If this property is not specified, then the default value is client-dependent. @@ -2051,7 +2070,7 @@ A reference from an Annotation Page to the following Annotation Page within an A The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the following Annotation or Collection Page. The value of the `type` property must be the string `AnnotationPage` or `CollectionPage`. * An AnnotationPage _MUST_ have the `next` property, unless it is the last page in the AnnotationCollection or Collection.
- Clients _MUST_ processs the `next` property on an AnnotationPage or CollectionPage. + Clients _MUST_ process the `next` property on an AnnotationPage or CollectionPage. {% include api/code_header.html %} ``` json-doc @@ -2153,9 +2172,9 @@ A reference from an Annotation Page to the preceding Annotation Page within an A The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the preceding Annotation or Collection Page. The value of the `type` property must be the string `AnnotationPage` or `CollectionPage`. * An AnnotationPage _SHOULD_ have the `prev` property, unless it is the first page in the AnnotationCollection.
- Clients _SHOULD_ processs the `prev` property on an AnnotationPage. + Clients _SHOULD_ process the `prev` property on an AnnotationPage. * A CollectionPage _SHOULD_ have the `prev` property, unless it is the first page in the Collection.
- Clients _SHOULD_ processs the `prev` property on a CollectionPage. + Clients _SHOULD_ process the `prev` property on a CollectionPage. {% include api/code_header.html %} ``` json-doc @@ -2206,7 +2225,7 @@ The organization or person is represented as an `Agent` resource. * Agents _MUST_ have the `label` property, and its value _MUST_ be a JSON object as described in the [languages][prezi30-languages] section. * Agents _SHOULD_ have the `homepage` property, and its value _MUST_ be an array of JSON objects as described in the [homepage][prezi30-homepage] section. * Agents _SHOULD_ have the `logo` property, and its value _MUST_ be an array of JSON objects as described in the [logo][prezi30-logo] section. -* Agents _MAY_ have the `seeAlso` property, and its value _MUST_ be an array of JSON object as described in the [seeAlso][prezi30-seealso] section. +* Agents _MAY_ have the `seeAlso` property, and its value _MUST_ be an array of JSON objects as described in the [seeAlso][prezi30-seealso] section. The value _MUST_ be an array of JSON objects, where each item in the array conforms to the structure of an Agent, as described above. @@ -2259,9 +2278,9 @@ The value _MUST_ be an array of JSON objects, where each item in the array confo A set of features or additional functionality that a linked resource enables relative to the linking or including resource, often for accessibility purposes and which are not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). -The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][link]. +The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][registry-accessibility]. -Note that the majority of the values have been selected from [accessibility feature spec][link] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. +Note that the majority of the values have been selected from the [W3C accessibility features vocabulary][registry-accessibility] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. * Annotations with the `supplementing` motivation _MAY_ have the `provides` property.
Clients _SHOULD_ ignore the `provides` property on all other resource. @@ -2337,7 +2356,7 @@ The value of the `refinedBy` property _MUST_ be a JSON Object, which _MUST_ desc The value of the region parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. -The value of `quality` _MUST_ be a string, and must conform to the requirements for the region parameter described in the Image API. +The value of `region` _MUST_ be a string, and must conform to the requirements for the region parameter described in the Image API. * The IIIF Image API Selector _MAY_ have the `region` property with exactly one value.
Clients _MUST_ process the `region` property on a IIIF Image API Selector. @@ -2399,7 +2418,7 @@ The value of the property _MUST_ be a JSON object, that has the `label` and `val ### rights {: #rights} -A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added in the [rights registry][break-until-there-is-a-registry]. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. +A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added in the [rights registry][registry-rights]. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is _RECOMMENDED_ to include the information using the `requiredStatement` property or in the `metadata` property. @@ -2487,7 +2506,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ### selector {: #selector} -The `selector` property on a Specific Resource references an array of Selector instances, any of which can be used to determine the desired region or part of the resource in the `source` property of the Specfic Resource. Each Selector in the array _SHOULD_ select the same content, however some Selector classes can be more precise than others. Publishers _SHOULD_ order the array based on the preferred Selector to use, likely the most accurate. Clients _MUST_ choose one of the Selectors to process, based on which are supported, in the preference order. +The `selector` property on a Specific Resource references an array of Selector instances, any of which can be used to determine the desired region or part of the resource in the `source` property of the Specific Resource. Each Selector in the array _SHOULD_ select the same content, however some Selector classes can be more precise than others. Publishers _SHOULD_ order the array based on the preferred Selector to use, likely the most accurate. Clients _MUST_ choose one of the Selectors to process, based on which are supported, in the preference order. For more information about Selectors and the `selector` property, please see the [Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#selectors). @@ -2643,7 +2662,7 @@ The value _MUST_ be a JSON Object with the `id` and `type` properties. The value A single Quantity that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance corresponding to the length of a single Canvas coordinate unit. A Canvas with a `width` of 5000 and a `spatialScale` with `quantityValue` of 0.00008 and a `unit` of `m` represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. -To assert a `spatialScale` for a Content Resource, the resource _MUST_ first be painted into a Container and the `spatialScale` is asserted on that Container. For example, a 3d model would be painted into a Scene, and then `spatialScale` is asserted on the Scene. +To assert a `spatialScale` for a Content Resource, the resource _MUST_ first be painted into a Container and the `spatialScale` is asserted on that Container. For example, a 3D model would be painted into a Scene, and then `spatialScale` is asserted on the Scene. * A Canvas _MAY_ have the `spatialScale` property.
Clients _SHOULD_ process `spatialScale` on a Canvas. @@ -2695,7 +2714,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert "source": "https://example.org/iiif/1/canvas/1", "selector": { "type": "PointSelector", - "t": 14.5 + "instant": 14.5 } } } @@ -2923,7 +2942,7 @@ The value _MUST_ be a string. ### total (totalItems) {: #total} -For compatability with ActivityStreams and the Change Discovery API, clients _SHOULD_ also accept `totalItems` as the name of this property. +For compatibility with ActivityStreams and the Change Discovery API, clients _SHOULD_ also accept `totalItems` as the name of this property. {: .note} The `total` property indicates the total number of annotations contained in an Annotation Collection, or the total number of Collections and Manifests within a Collection. A Collection _SHOULD_ have `total` if it uses pages, and _MAY_ have it if it does not, however the information is readily available by finding the length of the `items` array in the latter case. @@ -2986,7 +3005,7 @@ The value _MUST_ be a string. | `Audio`{: #value-Audio} | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | | `Dataset`{: #value-Dataset} | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | | `Image`{: #value-Image} | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | -| `Model`{: #value-Model} | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | +| `Model`{: #value-Model} | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3D javascript library | | `Text`{: #value-Text} | Resources primarily intended to be read | | `Video`{: #value-Video} | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | {: .api-table #table-type} @@ -3001,7 +3020,7 @@ For compatibility with previous versions, clients _SHOULD_ accept `Sound` as a s ### unit -The unit of measurement of a quantity expressed by a Quantity. This unit is necessary to interpet the value, as the same number could result in very different processing for different units: consider a physical scale of 1 meter vs 1 inch, and how clients might misrepresent the intent of the content of the Manifest. +The unit of measurement of a quantity expressed by a Quantity. This unit is necessary to interpret the value, as the same number could result in very different processing for different units: consider a physical scale of 1 meter vs 1 inch, and how clients might misrepresent the intent of the content of the Manifest. The value _MUST_ be a string value. This specification defines the values in the table below. Others may be registered via the IIIF unit registry. @@ -3073,6 +3092,21 @@ The value of the `via` property _MUST_ be an array of strings, and each string _ ``` +### viewHeight +{: #viewHeight} + +The height of the visible region for an OrthographicCamera, in the coordinate space of the Scene. Unlike a PerspectiveCamera which uses a field of view angle, an OrthographicCamera defines its visible region by a rectangular volume. The `viewHeight` gives the vertical extent of that region in Scene coordinate units; the corresponding horizontal extent is derived proportionally from the aspect ratio of the client's viewport. + +The value _MUST_ be a positive floating point number in the coordinate space of the Scene. If this property is not specified, then the default value is client-dependent. + +* An OrthographicCamera _SHOULD_ have the `viewHeight` property.
+ Clients _SHOULD_ process the `viewHeight` property on OrthographicCameras. + +```json-doc +{ "viewHeight": 40.0 } +``` + + ### viewingDirection {: #viewingDirection} @@ -3109,7 +3143,7 @@ The volume property represents the relative volume of an audio source. The `quan The value of this property _MUST_ be a Quantity. The `unit` property of the Quantity _MUST_ be `relative`. -The `value` property of the Quantity _MUST_ be between 0.0 and 1.0. +The `quantityValue` property of the Quantity _MUST_ be between 0.0 and 1.0. * Audio resource types _SHOULD_ have the `volume` property.
Clients _SHOULD_ process the `volume` property on an Audio resource. @@ -3154,7 +3188,7 @@ The value _MUST_ be a number (floating point or integer). * A PointSelector _MAY_ have the `x` property.
Clients _MUST_ process `x` on a PointSelector. * Transforms _MAY_ have the `x` property.
- Clients _MUST_ process `x` on a Transforms. + Clients _MUST_ process `x` on Transforms. * Other types of resource _MUST NOT_ have the `x` property.
Clients _SHOULD_ ignore `x` on other types of resource. @@ -3166,14 +3200,14 @@ The value _MUST_ be a number (floating point or integer). ### y {: #y} -A number giving the y coordinate of a point on the vertical or height axis (e.g. for Point Selector), an angular value in degrees around the y axis (e.g. for Rotate Transform), a scale factor to multiply another y value by (e.g. for Scale Transform), or an offset along the y axis to add to another x value (e.g. for Translate Transform). The interpretation of the value is, thus, dependent on the class of the resource that has the `y` property. +A number giving the y coordinate of a point on the vertical or height axis (e.g. for Point Selector), an angular value in degrees around the y axis (e.g. for Rotate Transform), a scale factor to multiply another y value by (e.g. for Scale Transform), or an offset along the y axis to add to another y value (e.g. for Translate Transform). The interpretation of the value is, thus, dependent on the class of the resource that has the `y` property. The value _MUST_ be a number (floating point or integer). * A PointSelector _MAY_ have the `y` property.
Clients _MUST_ process `y` on a PointSelector. * Transforms _MAY_ have the `y` property.
- Clients _MUST_ process `y` on a Transforms. + Clients _MUST_ process `y` on Transforms. * Other types of resource _MUST NOT_ have the `y` property.
Clients _SHOULD_ ignore `y` on other types of resource. @@ -3186,14 +3220,14 @@ The value _MUST_ be a number (floating point or integer). ### z {: #z} -A number giving the z coordinate of a point on the "depth" axis (e.g. for Point Selector), an angular value in degrees around the x axis (e.g. for Rotate Transform), a scale factor to multiply another x value by (e.g. for Scale Transform), or an offset along the x axis to add to another x value (e.g. for Translate Transform). The interpretation of the value is, thus, dependent on the class of the resource that has the `x` property. +A number giving the z coordinate of a point on the "depth" axis (e.g. for Point Selector), an angular value in degrees around the z axis (e.g. for Rotate Transform), a scale factor to multiply another z value by (e.g. for Scale Transform), or an offset along the z axis to add to another z value (e.g. for Translate Transform). The interpretation of the value is, thus, dependent on the class of the resource that has the `z` property. The value _MUST_ be a number (floating point or integer). * A PointSelector _MAY_ have the `z` property.
Clients _MUST_ process `z` on a PointSelector. * Transforms _MAY_ have the `z` property.
- Clients _MUST_ process `z` on a Transforms. + Clients _MUST_ process `z` on Transforms. * Other types of resource _MUST NOT_ have the `z` property.
Clients _SHOULD_ ignore `z` on other types of resource. @@ -3235,7 +3269,7 @@ Clients supporting dynamic content need to support - time extents - other activating annos -This specification defines the following client behaviors; others may be found in the [IIIF Cookbook][ref]. +This specification defines the following client behaviors; others may be found in the [IIIF Cookbook][annex-cookbook]. > enables first then disables (?) @@ -3314,4 +3348,4 @@ FIXME: Describe the registries * Provides * Unit -{: #scrolly-mc-scroll-face} +