Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

service uses target doc version, collections collect current doc version #1408

Merged
merged 2 commits into from
Feb 19, 2018
Merged

service uses target doc version, collections collect current doc version #1408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47374a1
service uses target doc version, collections collect current doc version
azaroth42 Feb 18, 2018
e5be25b
fix json, make stroop, zimeon wording changes
azaroth42 Feb 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions source/_includes/links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
[json-ld-68]: http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld "Interpreting JSON as JSON-LD"
[json-ld-compact]: http://www.w3.org/TR/json-ld-api/#compaction-algorithms "JSON-LD Compaction Algorithms"
[json-ld]: http://www.w3.org/TR/json-ld/ "JSON-LD"
[json-ld-scoped-contexts]: https://json-ld.org/spec/latest/json-ld/#scoped-contexts
[linked-data]: http://linkeddata.org/ "Linked Data"
[media-frags]: http://www.w3.org/TR/media-frags/#naming-space "Media Fragments"
[mellon]: http://www.mellon.org/ "The Andrew W. Mellon Foundation"
Expand Down
34 changes: 23 additions & 11 deletions source/api/presentation/3.0/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -577,7 +577,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ have the `id`,
##### service
A link to an external service that the client might interact with directly and gain additional information or functionality for using this resource, such as from an image to the base URI of an associated [IIIF Image API][image-api] service. The service resource _SHOULD_ have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the [Service Registry][registry-services] document for the details of currently known service types.

The value _MUST_ be an array of JSON objects. Each object _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label` and `profile` properties.
The value _MUST_ be an array of JSON objects. Each object will have properties depending on the service's definition, but _MUST_ have either the `id` or `@id` and `type` or `@type` properties. Each object _SHOULD_ have a `profile` property.

* Any resource type _MAY_ have one or more links to an external service.<br/>
Clients _MAY_ process `service` on any resource type, and _SHOULD_ process the IIIF Image API service.
Expand All @@ -590,7 +590,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ have the `id` a
}]}
```

For cross-version consistency, this specification defines the following values for the `type` field for backwards compatibility with other IIIF APIs. Future versions of these APIs will define their own types.
For cross-version consistency, this specification defines the following values for the `type` or `@type` field for backwards compatibility with other IIIF APIs. Future versions of these APIs will define their own types. These `type` values are necessary extensions for compatibility of the older versions.

| Value | Specification |
| -------------------- | ------------- |
Expand All @@ -602,15 +602,20 @@ For cross-version consistency, this specification defines the following values f
| AuthTokenService1 | [Authentication API version 1][auth-api-1-token] |
| AuthLogoutService1 | [Authentication API version 1][auth-api-1-logout] |

A reference from a version 3 Presentation API document to a version 2 Image API end point would thus follow the pattern in the example below. Consuming implementations should not expect to encounter the `type` and `profile` parameters in the representation returned from the `id`.
A reference from a version 3 Presentation API document to both version 2 and version 3 Image API endpoints would thus follow the pattern in the example below. API versions defined after Presentation API version 3.0 will follow the community best practices of `id` and `type`, but in the interim implementations _MUST_ be prepared to recognize the older property names. Note that the `@context` key _SHOULD_ not be present within the `service`, but instead included at the beginning of the document.

``` json-doc
{
"service": [
{
"id": "http://https://example.org/iiif/image1/identifier",
"type": "ImageService2",
"profile": "level1"
"@id": "http://https://example.org/iiif2/image1/identifier",
"@type": "ImageService2",
"profile": "http://iiif.io/api/image/2/level2.json"
},
{
"id": "http://https://example.org/iiif3/image1/identifier",
"type": "ImageService3",
"profile": "level2"
}
]
}
Expand Down Expand Up @@ -950,11 +955,11 @@ The value of the `@context` property _MUST_ be a list, and the __last__ two valu
}
```

Any additional fields beyond those defined in this specification or the Web Annotation Data Model _SHOULD_ be mapped to RDF predicates using further context documents. If possible, these extensions _SHOULD_ be added to the top level `@context` field, and _MUST_ be added before the above contexts. The JSON-LD 1.1 functionality of type and predicate specific context definitions _SHOULD_ be used if possible to try to minimize any cross-extension collisions.
Any additional fields 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` field, and _MUST_ be added before the above contexts. The JSON-LD 1.1 functionality of type and predicate specific context definitions, known as [scoped contexts]][json-ld-scoped-contexts], _MUST_ be used to minimize cross-extension collisions.

The JSON representation _MUST NOT_ include the `@graph` key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as described by this specification.
The JSON representation _MUST NOT_ include the `@graph` key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD 1.0 compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as described by this specification.

Embedded JSON-LD data that uses a JSON-LD version 1.0 context definition, such as references to older external services or extensions, _MAY_ require the context to be included within the service description, rather than listed in the top resource. Care should be taken to use the mappings defined by those contexts, especially with regard to `id` versus `@id`, and `type` versus `@type`, to ensure that clients receive the keys that they are expecting to process.
Embedded JSON-LD data that uses a JSON-LD version 1.0 context definition, such as references to older external services or extensions, _MUST_ be retrofitted to use a scoped context based either on a property or type, as per the examples in the definition of the `service` property. Care should be taken to use the mappings defined by those contexts, especially with regard to `id` versus `@id`, and `type` versus `@type`, to ensure that clients receive the keys that they are expecting to process.

## 5. Resource Structure

Expand Down Expand Up @@ -1390,11 +1395,18 @@ An example Collection document:
"behavior": ["top"],
"attribution": {"en": ["Provided by Example Organization"]},

"items": []

"items": [
{
"id": "https://example.org/iiif/1/manifest",
"type": "Manifest",
"label": {"en": "Example Manifest 1"}
}
]
}
```

Note that while the Collection _MAY_ include Collections or Manifests from previous versions of the API, the information included in this document _MUST_ follow the current version requirements, not the requirements of the target document. This is in contrast to the requirements of `service`, as there is no way to distinguish a version 2 Manifest from a version 3 Manifest by its `type`.

### 5.9. Paging

In some situations, Annotation Page resources or the list of Manifests in a collection may be very long or expensive to create. The latter case is especially likely to occur when responses are generated dynamically. In these situations the server may break up the response using [paging properties][prezi-api-3-paging]. The length of a response is left to the server's discretion, but the server should take care not to produce overly long responses that would be difficult for clients to process.
Expand Down