diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 824934f97..33d758c90 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -16,21 +16,21 @@ editors: - name: Michael Appleby ORCID: https://orcid.org/0000-0002-1266-298X institution: Yale University + - name: Dawn Childress + ORCID: https://orcid.org/0000-0003-2602-2788 + institution: UCLA - name: Tom Crane ORCID: https://orcid.org/0000-0003-1881-243X institution: Digirati + - name: Jeff Mixter + ORCID: https://orcid.org/0000-0002-8411-2952 + institution: OCLC - name: Robert Sanderson ORCID: https://orcid.org/0000-0003-4441-6852 - institution: J. Paul Getty Trust - - name: Dawn Childress - ORCID: https://orcid.org/0000-0003-2602-2788 - institution: UCLA + institution: Yale University - name: Julie Winchester ORCID: https://orcid.org/0000-0001-6578-764X institution: Duke University - - name: Jeff Mixter - ORCID: https://orcid.org/0000-0002-8411-2952 - institution: OCLC hero: image: '' --- @@ -2626,5 +2626,3 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S ## Acknowledgements ## Change Log - - diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 06f8415d7..e20cca1e1 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -627,9 +627,10 @@ An Animation Selector _MAY_ have the following properties: [id](#id) {: #ImageApiSelector} > `"type": "ImageApiSelector"` -The Image API Selector is used to describe the operations available via the IIIF Image API in order to retrieve a particular image representation. In this case the 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 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. In this case the 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 a default should be used. -The Image API Selector has properties following the parameters from the API, and record the values needed to fill out the URL structure in the request. If the property is not given, then a default should be used. | Property | Default | Description | | -------- | --------- | ----------------------------------------------------- | @@ -638,6 +639,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. | __Properties__
A IIIF Image API Selector _MUST_ have the following properties: [type](#type).

@@ -682,6 +684,8 @@ The following classes are typically used within Scenes. They might have utility A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. The first Camera defined in a Scene without the `hidden` behavior is the default Camera. Camera is an abstract class and _MUST NOT_ be instantiated directly. +If a Scene does not have any Cameras defined within it, then the client _MUST_ provide a default Camera. The type, properties and position of this default camera are client-dependent. If, at any time, there are no non-hidden cameras in a Scene, then the client _MUST_ provide a default Camera as if no Cameras were defined. + If either the position or direction is not specified, then the position defaults to the origin of the Scene, and the direction defaults to pointing along the z axis towards negative infinity. __Properties__
@@ -829,10 +833,9 @@ Spot Lights _MAY_ have the following additional properties: [lookAt](#lookAt) "angle": 15.0, "color": "#FFFFFF", "intensity": { - "id": "https://example.org/iiif/spotlight/1/value", "type": "Quantity", - "unit": "relative", - "quantityValue": 0.5 + "quantityValue": 0.5, + "unit": "relative" } } ``` @@ -916,10 +919,9 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo }, "angle": 45.0, "volume": { - "id": "https://example.org/iiif/value/1", "type": "Quantity", - "unit": "relative", - "quantityValue": 1.0 + "quantityValue": 1.0, + "unit": "relative" } } ``` @@ -1045,7 +1047,6 @@ A Quantity _MAY_ have the following properties: [id](#id) and [label](#label). {% include api/code_header.html %} ```json { - "id": "https://example.org/iiif/unit/2", "type": "Quantity", "quantityValue": 1.0, "unit": "m" @@ -1133,41 +1134,39 @@ The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and ` ### action {: #action} -Only valid on SpecificResource when bodies of activating annotations - -body of the activating anno is an ordered list of SpecificResource - -...which may have selectors eg for AnimationSelector -...but may just have action which are processed in order; client performs the action on the source. - -The client must perform all the actions; if it can't perform all of them it must not perform any. -If the activating annotation that is currently being processed is disabled as part of that processing, don't stop processing the ordered list, keep going through to the end. +The `action` property is used on Specific Resources that are in the `body` array of activating annotations (Annotations with the "activating" motivation). The values of the property are named actions which the client is being instructed to carry out upon the `source` of the Specific Resource. The list of possible values and their corresponding effects is given in the table below. Clients _MUST_ process the Specific Resources in the order given in the Annotation, and _MUST_ process the actions in the order given in the array. The client _MUST_ perform all of the actions on the respective resources, and if it cannot, then it _MUST NOT_ perform any of them. The set of actions within an Annotation is, thus, treated as an atomic transaction. If the activating annotation that is currently being processed is disabled as part of the processing, the client _MUST NOT_ stop processing the ordered list when this occurs but keep processing until the end of the current Annotation's set of actions. Each activating Annotation is processed completely before moving to another activating Annotation's actions, even if an action causes another activating Annotation's actions to be triggered. Instead, the activating Annotations are queued up in order that they are triggered, and when the client finishes one such annotation it can begin to process the next, and so on. -Only process one set of activating anno bodies at a time. If a body causes another activating anno to be triggered, queue up that activating anno and don't tackle it until you've finished processing all the bodies of the current one. +The possible values of `action` are: -values are: +| Value | Description | +| ------ | ----------- | +| enable | The acted-upon resource is now able to be selected, or, if it is an activating annotation, it is able to be triggered | +| disable | The acted-upon resource is not able to be selected or triggered | +| show | The "hidden" behavior is removed from the acted-upon resource, if it has it | +| hide | The "hidden" behavior is added to the acted-upon resource, if it does not have it | +| reset | The acted-upon resource is reset to its initial state, as if it (or its Container) had just been loaded for the first time | +| start | Time-based content resources or animations within resources that are not playing are started | +| stop | Time-based content resources or animations within resources that are playing are stopped| +| select | The acted-upon resource is selected for use, such as a Camera within a Scene | - * enable (make selectable, or makes an activating anno triggerable) - * disable (inverse) - * show (removes behavior:hidden) - * hide (applies behavior:hidden) - * reset (rewind AV to beginning) - * stop (animations in models; time-based content resources that are not painted into duration) - * start (ditto) - * select (rarely used because scope) +The value of `action` _MUST_ be an array of strings, where each item in the array is drawn from the above list or a registered extension. * A Specific Resource _MAY_ have the `action` property.
Clients _SHOULD_ process the `action` property on Specific Resources. * Other types of resource _MUST NOT_ have the `action` property.
Clients _SHOULD_ ignore `action` on other types of resource. +{% include api/code_header.html %} +```json + "action": ["show", "enable"] +``` ### angle {: #angle} The `angle` property is used with SpotLights and Spot Audio Emitters to define the radius of the cone of emitted light or sound. Note that the `fieldOfView` property is defined as the entire field of view, not half (as might be inferred from `angle` using radius). -The value _MUST_ be a floating point number greater than 0 and less than 90, and is measure in degrees. If this property is not specified, then the default value is client-dependent. +The value _MUST_ be a floating point number greater than 0 and less than 90, and is measured in degrees. If this property is not specified, then the default value is client-dependent. * A SpotLight _SHOULD_ have the `angle` property.
Clients _SHOULD_ process the `angle` property on SpotLights. @@ -1217,7 +1216,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. -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 client-dependent. +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 client-dependent. * A Canvas _MAY_ have the `backgroundColor` property
Clients _SHOULD_ render `backgroundColor` on any resource type. @@ -1250,9 +1249,6 @@ The value _MUST_ be an array of strings. * Any resource type _MAY_ have the `behavior` property with at least one item.
Clients _SHOULD_ process `behavior` on any resource type. - -TODO: Address https://github.com/IIIF/api/issues/2318 - | Value | Description | | ----- | ----------- | || **Temporal Behaviors** | @@ -1309,15 +1305,13 @@ The value _MUST_ be an array of JSON objects. ### canonical {: #canonical} -The URI that SHOULD be used to track the resource's identity, regardless of where it is made accessible or its `id` property. The canonical URI can then be used as the target for annotations, regardless of the URI from which it was retrieved. If this property is set, then clients _MUST NOT_ change or delete it. Clients _MUST NOT_ assign a canonical URI if one is not present, as the resource might already have one assigned by a different system but it was not included in the representation received. Any reference to the `canonical` URI _MUST_ be treated as a reference to this resource. - -As the W3C model allows the property to be used on bodies and targets, and any resource _MAY_ be a body or target of an Annotation, this property _MAY_ be used on any resource in the IIIF specifications. +The URI that _SHOULD_ be used to track the resource's identity, regardless of where it is made accessible or the value of its `id` property. The canonical URI can then be used as the target for annotations, regardless of the URI from which it was retrieved. If this property is set, then clients _MUST NOT_ change or delete it. Clients _MUST NOT_ assign a canonical URI if one is not present, as the resource might already have one assigned by a different system but was not included in the representation received. Any reference to the `canonical` URI _MUST_ be treated as a reference to this resource. For more information about `canonical`, see the [W3C Annotation Model](https://www.w3.org/TR/annotation-model/#other-identities). The value _MUST_ be a string, and the value must be an absolute HTTP(S) URI. -* Any resource _MAY_ have the `canonical` property. +* Any resource _MAY_ have the `canonical` property.
Clients _MAY_ process the `canonical` property on any resource. {% include api/code_header.html %} @@ -1367,7 +1361,7 @@ The value _MUST_ be a positive floating point number. ### exclude {: #exclude} -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type or functionality should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. +Just as a Scene may contain multiple Annotations with models, light, and cameras, a single 3D model file can also contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes, or models that themselves may contain multiple resources, into a Scene, it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation's body resource being painted into a Scene. When `exclude` is used, the excluded resource type or functionality should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. | Value | Description | |------------|-------------| @@ -1378,7 +1372,7 @@ Just as a Scene may contain multiple Annotations with model, light, and camera r The value of `exclude` is an array of strings, each of which is one of the values listed above. If the `exclude` property is not specified, then no resources are excluded. -* An Annotation _MAY_ have the `exclude` property. +* An Annotation _MAY_ have the `exclude` property.
Clients _SHOULD_ process the `exclude` property. ```json @@ -1390,9 +1384,9 @@ The value of `exclude` is an array of strings, each of which is one of the value This property gives the distance along the axis of the camera's orientation after which objects are no longer visible. Objects further from the camera than the `far` 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 greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. +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 greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. -* A Camera _MAY_ have the `far` property
+* A Camera _MAY_ have the `far` property.
Clients _SHOULD_ process the `far` property on Cameras. ```json-doc @@ -1429,14 +1423,14 @@ The value _MUST_ be a positive integer. ### first {: #first} -This property references the first Annotation Page within an Annotation Collection, or the first CollectionPage within a Collection. Note that Collections will only have the `first` property if there is a large number of items, more than could conveniently be included in a single page. +This property references the first Annotation Page within an Annotation Collection, or the first Collection Page within a Collection. Note that Collections will only have the `first` property if there is a large number of items, more than could conveniently be included in a single page. The value _MUST_ be a JSON object with `id` and `type` properties. The `id` _MUST_ be the HTTP(S) URI of the referenced Annotation or Collection Page. The value of `type` _MUST_ be `AnnotationPage` or `CollectionPage`. -* A non-empty AnnotationCollection _MUST_ have the `first` property.
+* A non-empty Annotation Collection _MUST_ have the `first` property.
Clients _MUST_ process the `first` property on an AnnotationCollection. -* A non-empty Collection _MAY_ have the `first` property.
- Clients _MUST_ process the `first` property on a Collection. +* A non-empty Collection with pages _MUST_ have the `first` property.
+ Clients _MUST_ process the `first` property on a paged Collection. {% include api/code_header.html %} ``` json-doc @@ -1452,13 +1446,13 @@ The value _MUST_ be a JSON object with `id` and `type` properties. The `id` _M ### format {: #format} -For Content resources, the `format` property records the specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. The value of the property should thus be the same as the value of the `Content-Type` header returned when the URI of the Content Resource is dereferenced. +For Content Resources, the `format` property records the specific media type (often called a MIME type), for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. The value of the property should thus be the same as the value of the `Content-Type` header returned when the URI of the Content Resource is dereferenced. For the IIIF Image API Selector class however, the value of `format` is the parameter to use in the Image API URL construction, and thus to request a jpeg image, the value would be `jpg` instead. The value _MUST_ be a string, and _SHOULD_ either be a valid media type or an image extension format valid for the IIIF Image API. - * A content resource _SHOULD_ have the `format` property.
+ * A Content Resource _SHOULD_ have the `format` property.
Clients _MAY_ render the `format` of any content resource. * A IIIF Image API Selector class _SHOULD_ have the `format` property.
Clients _MUST_ process the `format` property on a IIIF Image API Selector. @@ -1482,13 +1476,13 @@ For a IIIF Image API Selector: ### height {: #height} -The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. +The height of the Canvas or external Content Resource. For Content Resources, the value is in pixels. For Canvases, the value does not have a unit. Instead, in combination with the `width` property, it conveys an aspect ratio for the space in which Content Resources are located. The value _MUST_ be a positive integer. * A Canvas _MUST_ have the `height` property.
Clients _MUST_ process `height` on a Canvas. - * Content resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
+ * Content Resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
Clients _SHOULD_ process `height` on content resources. * Other types of resource _MUST NOT_ have the `height` property.
Clients _SHOULD_ ignore `height` on other types of resource. @@ -1500,7 +1494,7 @@ The value _MUST_ be a positive integer. ### homepage {: #homepage} -A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. +A web page that is about the entity represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the entity, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have the `id`, `type`, and `label` properties, _SHOULD_ have a `format` property, and _MAY_ have the `language` property. @@ -1529,7 +1523,7 @@ Please note that this specification has stricter requirements about the JSON pat ### id {: #id} -The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Containers, which _MUST_ have their own URI without a fragment. +The URI that identifies the resource. If the resource is only available embedded within another resource, such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Containers, which _MUST_ have their own URI without a fragment. The value _MUST_ be a string, and the value _MUST_ be an absolute HTTP(S) URI for resource classes defined or described in this specification. If the resource is retrievable via HTTP(S), then the URI _MUST_ be the URI at which it is published. External resources, such as profiles, _MAY_ have non-HTTP(S) URIs defined by other communities. @@ -1576,26 +1570,26 @@ The value of the `quantityValue` property of the Quantity _MUST_ be between 0.0 ```json { "intensity": { - "id": "https://example.org/iiif/intensity/1", - "type": "Quantity", - "quantityValue": 0.5, - "unit": "relative"} + "type": "Quantity", + "quantityValue": 0.5, + "unit": "relative" + } } ``` ### interactionMode {: #interactionMode} -TODO clarify how `interactionMode` corresponds to `action` +A set of features that guide or limit user interaction with content within a Container that the publisher of the content would prefer the client to use when presenting the resource. This specification defines values in the table below that guide interactions with Cameras within a Scene. Other values for other Container types or specifying other interaction modes for 3D content may be defined externally as an [extension][prezi30-ldce]. For interaction modes pertaining to Cameras within a Scene, the client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Cameras when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). If `interactionMode` is not set for a Camera, then the mode to be used is client-dependent. -A set of features that guide or limit user interaction with content within a Container that the publisher of the content would prefer the client to use when presenting the resource. This specification defines values in the table below that guide interactions with Cameras within a Scene. Other values for other Container types or specifying other interaction modes for 3D content may be defined externally as an [extension][prezi30-ldce]. For interaction modes pertaining to Cameras within a Scene, the client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Cameras when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). +When `interactionMode` is specified on a Scene and no Cameras are supplied within the Scene, then the default Camera created by the viewer _SHOULD_ have the given mode. Other specific Cameras within the Scene _MAY_ have different `interactionMode` values. When more than one interaction mode is present, the client _SHOULD_ pick the first interaction mode that the client is capable of supporting. For interaction modes that involve a Camera orbiting around a target point, the target point _SHOULD_ be the same as the Camera's `lookAt` property. -The value _MUST_ be an array of strings. +If `action` is used to "disable" a Camera, then it is the same as if it were in the "locked" `interactionMode`. Thus a Camera can meaningfully be not hidden, selected, and disabled at the same time. -> TODO: Undecided whether this is Camera and/or Container +The value _MUST_ be an array of strings. * A Camera _MAY_ have the `interactionMode` property.
Clients _SHOULD_ process `interactionMode` on a Camera. @@ -1620,12 +1614,14 @@ The value _MUST_ be an array of strings. ### items {: #items} -Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. +Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Containers within a Manifest. All of these situations are covered with a single property, `items`. The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties. The items will be resources of different types, as described below. - * A Collection _MUST_ have the `items` property. Each item _MUST_ be either a Collection or a Manifest.
+ * A Collection _MUST_ either have the `items` property or the `first` and `last` properties. If present, each item _MUST_ be either a Collection or a Manifest.
Clients _MUST_ process `items` on a Collection. + * A Collection Page _MUST_ have the `items` property. Each item _MUST_ be either a Collection or a Manifest.
+ Clients _MUST_ process `items` on a Collection Page. * A Manifest _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Container.
Clients _MUST_ process `items` on a Manifest. * A Container _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation Page.
@@ -1682,7 +1678,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language ### language {: #language} -The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. +The language or languages used in the content of this external resource. It _MAY_ be used for resources [referenced][prezi30-terminology] from `body`, `target`, `source`, `homepage`, `rendering`, and `partOf`, amongst others. The value _MUST_ be an array of strings. Each item in the array _MUST_ be a valid language code, as described in the [languages section][prezi30-languages]. @@ -1755,7 +1751,6 @@ If the value is a PointSelector, then the light or camera resource is rotated ar This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. - The value _MUST_ be a JSON object, conforming to either a reference to an Annotation, or an embedded PointSelector. If this property is not specified, then the default value for cameras is to look straight backwards (-Z) and for lights to point straight down (-Y). * A Camera _MAY_ have the `lookAt` property.
@@ -1808,22 +1803,22 @@ Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ exp This specification defines three values for the [Web Annotation Data Model][org-w3c-webanno] property of `motivation`, or `purpose` when used on a Specific Resource or Textual Body. -While any resource _MAY_ be the `target` of an Annotation, this specification defines only motivations for Annotations that target Containers. These motivations allow clients to determine how the Annotation should be rendered, by distinguishing between Annotations that provide the content of the Container, from ones with externally defined motivations which are typically comments about the Container. +These motivations allow clients to determine how the Annotation should be rendered, by distinguishing between Annotations that provide the content of the Container ("painting" motivation) and content from the Container ("supplementing" motivation), from ones with externally defined motivations which are typically comments about the Container. The "activating" motivation determines interactions with the resource in the Container. Additional motivations may be added to the Annotation to further clarify the intent, drawn from [extensions][prezi30-ldce] or other sources. Clients _MUST_ ignore motivation values that they do not understand. Other motivation values given in the Web Annotation specification _SHOULD_ be used where appropriate, and examples are given in the [Presentation API Cookbook][annex-cookbook]. | Value | Description | | ----- | ----------- | -| `painting` | Resources associated with a Container by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Container. The content can be thought of as being _of_ the Container. The use of this motivation with target resources other than Containers is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of a Canvas is an instruction to present that Image as (part of) the visual representation of the Canvas. Similarly, a textual body is to be presented as (part of) the visual representation of the Container and not positioned in some other part of the user interface.| +| `painting` | Resources associated with a Container by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Container. The content can be thought of as being _of_ the Container. The use of this motivation with target resources other than Containers is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of a Canvas is an instruction to present that Image as (part of) the visual representation of the Canvas. Similarly, a textual body is to be presented as (part of) the visual representation of the Container and not positioned in some other part of the user interface.| | `supplementing` | Resources associated with a Container by an Annotation that has the `motivation` value `supplementing` _MAY_ be presented to the user as part of the representation of the Container, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Container. The use of this motivation with target resources other than Containers is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of a Canvas is an instruction to present that Image to the user either in the Canvas's rendering area or somewhere associated with it, and could be used to present an easier to read representation of a diagram. Similarly, a textual body is to be presented either in the targeted region of the Container or otherwise associated with it, and might be OCR, a manual transcription or a translation of handwritten text, or captions for what is being said in a Timeline with audio content. | -| `activating` | Annotations with the motivation `activating` are referred to as _activating_ annotations, and are used to link a resource that triggers an action with the resource(s) to change, enable or disable. See [Dynamic Content]() for processing. | +| `activating` | Annotations with the motivation `activating` are referred to as _activating_ annotations, and are used to link a resource that triggers an action with the resource(s) to change, and the type of change to put into effect. See the [`action`](#action) property for information about processing actions. | {: .api-table #table-motivations} ### navDate {: #navDate} -A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. +A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Containers that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _MUST_ have a timezone, and _SHOULD_ be given in UTC with the `Z` timezone indicator, but _MAY_ instead be given as an offset of the form `+hh:mm`. @@ -1893,7 +1888,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 Cameria'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. @@ -1977,12 +1972,14 @@ The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `t ### position {: #position} -It is important to be able to position the (textual) body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. +It is important to be able to position the body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. The body resource _MUST_ be either a `TextualBody` or a `SpecificResource`. The value of this property _MUST_ be a JSON object conforming to the `SpecificResource` pattern of the Web Annotation Model. The Specific Resource _MUST_ have a `source` property that refers to a Container, and a `selector` that describes a point or region within the Container. -* A TextualBody _MAY_ have the `position` property.
- Clients _SHOULD_ process the `position` property on TextualBody instances. +* A Textual Body _MAY_ have the `position` property.
+ Clients _SHOULD_ process the `position` property on Textual Body instances. +* A Specific Resource _MAY_ have the `position` property.
+ Clients _SHOULD_ process the `position` property on Specific Resource instances. * Other classes _MUST NOT_ have the `position` property.
Clients _MUST_ ignore the `position` property on all other classes. @@ -2031,7 +2028,7 @@ The value must be a JSON object, with the `id` and `type` properties. The value A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. -The value _MUST_ be a string, either taken from the [profiles registry][registry-profiles] or a URI. +The value _MUST_ be a string, either taken from the [profiles registry][registry-profiles] or a full URI. * Resources [referenced][prezi30-terminology] by the `seeAlso` or `service` properties _SHOULD_ have the `profile` property.
Clients _SHOULD_ process the `profile` of a service or external resource. @@ -2112,6 +2109,8 @@ The value _MUST_ be an array of strings, each string identifies a particular fea 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`. +> TODO: clarify the list and get the descriptions from the accessibility folks + * Annotations with the `supplementing` motivation _MAY_ have the `provides` property.
Clients _SHOULD_ ignore the `provides` property on all other resource. @@ -2139,7 +2138,9 @@ Note that the majority of the values have been selected from [accessibility feat ### quality {: #quality} -The value of the quality parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. +The quality parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. + +The value of `quality` _MUST_ be a string, drawn from the list of acceptable qualities for the Image API. * The IIIF Image API Selector _MAY_ have the `quality` property with exactly one value.
Clients _MUST_ process the `quality` property on a IIIF Image API Selector. @@ -2154,16 +2155,16 @@ The value of the quality parameter in the IIIF Image API URL structure, as recor ### quantityValue {: #quantityValue} -The `quantityValue` property of a Quantity conveys its numerical component. +The `quantityValue` property of a Quantity conveys its numerical component, used with `unit` to determine how to interpret the number relative to quantities. The value of `quantityValue` _MUST_ be a floating point number. -* A Quantity _MUST_ have the `quantity` property.
- Clients _MUST_ process the `quantity` property on a Quantity. +* A Quantity _MUST_ have the `quantityValue` property.
+ Clients _MUST_ process the `quantityValue` property on a Quantity. {% include api/code_header.html %} ``` json-doc -{ "quantity": 0.1234123 } +{ "quantityValue": 0.1234123 } ``` ### refinedBy @@ -2189,6 +2190,8 @@ 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 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. * Other types of resource _MUST NOT_ have the `region` property.
@@ -2203,7 +2206,7 @@ The value of the region parameter in the IIIF Image API URL structure, as record ### rendering {: #rendering} -A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. +A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Container, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue otherwise represented as an Image on a Canvas. The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have the `format` and `language` properties. @@ -2223,6 +2226,8 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `t ] } ``` + + ### requiredStatement {: #requiredStatement} @@ -2243,26 +2248,11 @@ The value of the property _MUST_ be a JSON object, that has the `label` and `val } ``` -### resets -{: #resets} - -FIXME: write this - - -{% include api/code_header.html %} -``` json-doc -{ - "resets": [] -} -``` - ### 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 via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. - -!!! registration not extension +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. 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. @@ -2284,7 +2274,9 @@ The machine actionable URIs for both Creative Commons licenses and RightsStateme ### rotation {: #rotation} -The value of the rotation parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. Note well that the value _MUST_ be a string, not a number, in order to allow for the "!" character which indicates a mirror image. +The value of the rotation parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. + +The value _MUST_ be a string, not a number, in order to allow for the "!" character which indicates a mirror image. * The IIIF Image API Selector _MAY_ have the `rotation` property with exactly one value.
Clients _MUST_ process the `rotation` property on a IIIF Image API Selector. @@ -2417,6 +2409,8 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re The value of the size parameter in the IIIF Image API URL structure, as recorded in an Image API Selector. +The value of `size` _MUST_ be a string, and conform to the size parameter definition of the IIIF Image API. + * A IIIF Image API Selector _MAY_ have the `size` property with exactly one value.
Clients _MUST_ process the `size` property on a IIIF Image API Selector. * Other types of resource _MUST NOT_ have the `size` property.
@@ -2733,7 +2727,7 @@ The value _MUST_ be a string. For compatability 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. +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. The value of this property _MUST_ be a non-negative integer. @@ -2794,7 +2788,6 @@ The value _MUST_ be a string. | `Dataset` | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | | `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | | `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | - | `Text` | Resources primarily intended to be read | | `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | {: .api-table #table-type} @@ -2811,7 +2804,9 @@ For compatibility with previous versions, clients _SHOULD_ accept `Sound` as a s The unit of measurement of a quantity expressed by a Quantity. -The value _MUST_ be a string value. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. +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. + +> TODO: create registry and link it here | Value | Unit | |----------|-----------| @@ -2834,7 +2829,7 @@ The `value` property is used in several situations to convey a value of a resour In the `metadata` and `requiredStatement` properties, the `value` property is used to record the text of the metadata field or statement. The value of the property in this case is a [language map](#language-of-property-values) represented as a JSON object, as previously described. -Many selector classes use `value` to convey a string representation of the selection definition, such as `FragmentSelector` and `WktSelector`. The `TextualBody` similarly uses `value` to convey the string of the body of an Annotation. In these cases the value of `value` _MUST_ be a string. +Many selector classes use `value` to convey a string representation of the selection definition, such as `FragmentSelector` and `WktSelector`. The `TextualBody` similarly uses `value` to convey the string of the body of an Annotation, and `CssStylesheet` uses it to embed a short snippet of CSS. In these cases the value of `value` _MUST_ be a string. Language Map `value`: @@ -2843,12 +2838,16 @@ Language Map `value`: {"value": { "en": [ "Example Description" ]}} ``` -Selector or TextualBody `value`: +Embedded CssStylesheet, Selector or TextualBody `value`: {% include api/code_header.html %} ```json-doc { "value": "Example Textual Body" } ``` +### version + +> TODO: write me + ### via @@ -2868,12 +2867,10 @@ The value of the `via` property _MUST_ be an array of strings, and each string _ ### viewingDirection {: #viewingDirection} -!!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest +!!! TODO: Rewrite to be where is the navigation control to step to the next/ previous in the items of the manifest -The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, -if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the -list is to the right. +The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the list is to the right. The value _MUST_ be a string. @@ -2913,10 +2910,15 @@ The `value` property of the Quantity _MUST_ be between 0.0 and 1.0. {% include api/code_header.html %} ``` json-doc -{ "volume": { "type": "Quantity", "unit": "relative", "quantityValue": 0.5 } } +{ + "volume": { + "type": "Quantity", + "quantityValue": 0.5, + "unit": "relative" + } +} ``` - ### width {: #width}