iiif / api

Source for API and model specifications documents (api and model)

Specifications

Markdown Source of specifications documents

To Debug the Site

1. bundle install

2. Run rake dev to compile the site and run a dev server on http://localhost:4000.

To Run the Tests

1. bundle install
2. Install grunt npm install -g grunt-cli
3. Install grunt dependencies npm install
4. Run rake ci

To Publish the Site to iiif.io

Branches are available at http://preview.iiif.io/api/[branch_name]/api/index.html. The master branch is automatically loaded to the iiif.io website.

Some Things to Note

• Much of the site data is in the YAML files in _data/ (e.g. member institutions, server impls, demos, etc.) make edits there.
• The latest versions of the APIs are set in _config.yml. Change there will get pushed to .htaccess, technical-details/, and any other links.
• The website is now split with the specification website living here and the main website living in IIIF/website. Links internal and external should be in the following forms:
  • Internal relative link inside the API website [hyperlink text]({{ site.api_url }}/end/point)
  • link from the API website to the main website (not relative to this repo) [hyperlink text]({{ site.root_url }}/end/point)
  • External link [anchor-text](http://example.com/end/point)
  • Reference link [text][link_name] where link_name is expanded at the bottom of the page.
• If this branch has a domain name associated with it e.g. prezi3.iiif.io then add the name of the branch to the ROOT_BRANCHES variable in the .travis.yml. Note branch names are sperated by a space.

Contributions

Participation in the IIIF community is welcome in all forms, from any individual or organization. Please see the community page for more details about how to join in discussions.

Contributions to the text of the specifications and the content of the website are welcome in the form of pull requests, or by comments with proposed text on issues. By making such a contribution, the contributor asserts that they have the right to license the contribution such that content may be published under the CC-BY license by the IIIF Consortium, per the license statement on all documents.

api's Issues

meta: incompatible milestones

With multiple specifications out of sync in terms of versioning, I propose milestones should include the API name, eg. img1.2 and md1.1

Then we can meaningfully assign due dates to them.

Canonical URIs

It should be possible for a client to request an image and avoid any potential redirects. Furthermore, level 0 implementations may only have one URI that 'works'.

• Should we recommend adding rel=canonical to the Link header? And if so, to what?
• Need a recommendation on float v int for rotation
• What about the #level0 case (all static images)
• Canonical URI should prefer pixels over pct, due to:
  • The pct:50 problem with odd pixel dimensions as a justification
  • And floating point percents being inaccurate

Region canonical = ‘full’ if the whole thing else pixels, and never pct
Size canonical = full if the native size else w,h
Rotation canonical = 0 (as integer if possible, trim trailing zeros if decimal)
Quality = native if native is what you requested, else lower format is required

Add link header with rel="canonical"

Script to make HTML from MD version

It would be nice to have a script that

• Uses Python-Markdown (I say this library because I know it makes nice internal IDs) to derive HTML
• Validates all of the JSON in the spec
• Includes any necessary CSS references, (links to stylesheets and classes).

It won't be a pretty thing, but it should make it easier to do quick releases to fix typos, etc.

Styles

Example URIs should not be linked, as they will never resolve. Enclose in `s or otherwise prevent auto-linking.

I still don't like the `s in the 4.7 table. The box around them doesn't convey the right message (an example or code). Would prefer "s

Name for "metadata" "API"?

The term metadata is overloaded, especially with NSA collection of "metadata", and generates an assumption that it will include full bibliographic, semantic metadata. Instead the api is used in order to drive a display environment and explicitly contains NO semantics. At most it deals with structural metadata for the resources. While it's not really an API with dynamic parameters, in the future it might be with addition of other REST functionality for management.

Some options to replace metadata...

... focusing on the server side description of the layout of the resources:
"layout"
"arrangement"
"composition" -- confusing as might be interpreted as building new resources

... focusing on the client side display of the resources:
"display"
"presentation"
"rendering" / "rendition" -- confusing as might be interpreted that server renders the resources, rather than a description for the client to render.

scale-specific tile sizes

Need to get to the bottom of this, but there is at least one case, possibly two:

• If a JP2 uses precincts, it likely has a different tile size for each decomposition level
• If a JP2 uses tiles, the tiles may (I'm not 100% sure, but I think so) scale down at the same rate

Should this be reflected in info.json?

bitonal: Is there a recommended algorithm for this?

No, was the decision, but the spec should be clear about it

Associate IIIF service with partial image

Documentation Improvement: The specification does not say how to have part of an image aligned with a canvas, with a service associated with the entire image.

The correct method to record this state is:

{"resource" : {
    "@type" : "oa:SpecificResource", 
    "full" : {
      "@id": "http://example.org/images/spread.jpg",
      "height" : 1400,
      "width" : 2000,
      "service": {
        "@id" : "http://example.org/iiif/spread",
        "profile" : "...#level2"
      }
    },
    "selector" : {
      "@type": "sc:FragmentSelector",
      "value": "xywh=10,15,800,1200"
    }
  },
 "on" : ".../canvas/p1.json"
}

Rotation algorithm

It's unclear what algorithm to use for rotating an image. Because different algorithms vary in how they create partial pixels, the source image rotated at 22.5 degrees won't always be exactly 212 px wide.

Clarify metadata on Sequence vs Manifest

Documentation Improvement: The specification could be more clear about the usage of metadata fields on a Sequence rather than on the Manifest, and what different sequences relate to.

Convert metadata spec to markdown

Metadata spec should be markdown like image api.

Key in info.json should be "capabilities"

We call it capabilities ... so the key should be capabilities, not features.

2 forms, no 3, wait, I'll come in again...

Now with the features response, there are 3 possible requests. Need to change intro to section 2.

SharedCanvas Zones in IIIF

Requested Feature: MITH use Zones extensively in the Shelley Godwin Archive from the Shared Canvas ontology. These are not available in the IIIF Metadata specification, and hence are preventing them from adopting it. University of York also need it (2/26)

Notes:

• Zones are separately manipulable regions (like a mini-canvas on top of another canvas) - think spinners, volvels, parts of letters, paste-downs, fold-outs, etc.
• Discussion is required as to whether, and if so how, to do this.
• IIIF should engage with this issue
• Defer further discussion. Rob will put forward proposal “sooner” than next IIIF meeting.

Drop Rotation to level 2

... even for 90' increments, as it's not very useful. Easier to get a good 0 rotation image and rotate on the client side.

Otherwise services that implement everything but not rotation are only level 0, which seems weird.

(+1s from Jon and Chip on IIIF-Discuss)

Finer Granularity of Service Description

AKA "Capabilities", AKA "Profiles"

_Solution:_
See: https://gist.github.com/jpstroop/9102706
Profile URIs (#level0, etc) should also become capabilities instances.

_Background:_
There is an argument in favor of a finer granularity of service description than just the profile link.

• Unlike other systems (PMH, SRU, etc) the description can be automatically generated by a server without requiring any human intervention.
• The development effort to do so is likely minimal.
• The profile doesn't help clients know what they can request that is above the profile, it's the minimum level of support. If they knew they could use w,h (for example) they may make different requests.
• It could be just an extension to the current info.json so backwards compatible -- you claim conformance to the highest level profile that you support everything for, and then claim additional feature support to avoid massive info.json files.
• The conformance doc could provide json docs that list out all of the features supported at a particular level for clients to use as defaults.
• Level X is still useful as marketing, or requirements for RFPs on image servers, but that's likely about as far as it goes in the current incarnation
• Possible approach: server wide profile document, with overrides per image in info.json, defaulting to a profile document associated with the conformance level claimed. (What overrides would ever happen? And isn't format essentially determined by the server code, so could be in profile doc only? Quality determined by server code and source image).

Recto/Verso on Canvas for book modality

Requested Feature: Add explicit recto/verso flag on a canvas to enable page turning applications to correctly determine whether to have the first canvas start on the recto or verso of an opening. Must work with top-to-bottom as well as left to right, eg for flip charts/flip books.

Decision:

• Allow a new field to say that the canvas is not part of the page turning paradigm, even though it's part of the sequence.
• The first canvas is explicitly a "single", not part of a recto/verso pair. If this is not the case, then either mark it as not to be rendered in a page turner, or create an empty canvas at the beginning to represent the single rather than spread.
• Applies only to "paged" viewingHint, and directionality comes from existing "viewingDirection" property.

Editor's Proposal:

• Allow viewingHint on canvas and add "non-paged" to enumerated values
  Example:

{
  "@id": "http://example.org/iiif/book1/canvas/f1r-curtain.json",
  "@type" : "sc:Canvas",
  "viewingHint" : "non-paged",
  "height" : 1200,
  "width" : 800,
  "images" : [...]
}

What's the difference between "native" and "color"?

... I see: "Color: The image is returned in full color, typically using 24 bits per pixel." Are we encouraged to downsample to 24 bits?
Should we oversample if the source is lower?
When would a user ever opt for 'color' over 'native'? _Answer:#level0
_Also: REMOVE 24 bits from the text

Trailing punctuation in tables

Just a style thing. We have a lot of tables like this:

Thing	Description
blah	Blah blah blah blah blah

And sometimes we have training stops or question marks (for bools), sometimes we don't.

Make CORS mandatory

See #4

Add gravity to metadata

I didn’t found a solution for gravity in the metadata. I suppose you know about the term from Imagemagick.

The direction you choose specifies where to position subimages.

This is the answer for the question: where is the most important part of the image? The indispensable part that should be visible at every modification of the image.

This feature make images robust for transformations. The image creator decides once, what’s important. Then the image user transforms the image with creators hint in mind.

Example

You did it already in the demo. The second option for regions in the demo is what I call gravity:

1400,1200,2500,1075

Current implementation

Now I use only the naive implementation of this feature. Every image is split into 9 parts. I store the part as an abbreviation like “rb” (right-bottom). If the image size changes, the client software resizes the image according to the gravity I set once. It works for the majority of images.

I would like to store the gravity in same format as region. What do you think about it?

Auth and Rights

Current spec says:

Note that while there is widespread agreement that the limitation of WWW-Authenticate to Basic and Digest authentication in the current HTTP specification, there is no standard way to indicate appropriate redirection to a login screen, or convey a URI template to insert a return URI.

Which doesn’t make sense so needs correction. Also would be good to discuss practical issues of how auth is being done. Once authenticated it seems that authorization cookie tokens are the means all(?) implementations use to grant access. This happens automagically in the browser but should perhaps specified so that mediated or non-browser applications know to expect to have to get and keep cookies.

Scenarios.

1. Everything open, no auth: Normal info.json, specifies all info about images available, no login
2. Nothing available without auth: Access to info.json or any image URI is denied with 401, redirect to auth (can’t use login in info.json??)
3. Better access with auth: Base info.json has information about available images/tiles without auth, has login information, client will know to request only stuff that is available but can display login link. If client does auth then will get redirect to new info.json with different prefix and possibly different identifier. The new info.json will have all appropriate image information accessible with the new credentials.

Implementation logic (possible):

• Viewer either gets 401 or it gets info.json with “login” url (suggesting there is possibly a higher quality image available)
• It can offer the user a possibility to login
• It displays login url (in an iframe or new browser window)
• It re-request the info.json for all the opened images from the server
• Either it is redirected (HTTP) to a new location (iiif prefix)
• Or the info.json is changed (possibly new width / height, etc).

See this gist for how the new info.json might look.

comma missing after the qualities property

There's a comma missing after the qualities property [in the JSON example]

Change website references to the iiif.io domain

See #4

However, older versions (< 1.2) of the spec should keep the old library.stanford.edu namespace.

For non-90-degree rotations the API does not specify the background color?

... Does it have to be a constant color?

_Solution:_

• Move into implementation note about rotation.
• Be explictly inexplicit -- change “For non-90-degree rotations the API does not specify the background color.” to leave off the trailing “color”.

Link to a Logo

Requested Feature: Allow a named link to a logo or icon to use for the object, especially collections and manifests. Clients could use the logo in a grid or list to represent the object, or as branding in a display.

Suggested method:

  {"logo" : "http://example.org/logos/logo.jpg"}

Three separate use-cases

• contextual/institutional logo: context for the item (like institution but not necessarily)
  Decision: use logo (foaf:logo)
• content summarizing image: add at manifest, sequence, range, etc
  recommend iiif image service available for the image
  Editor Proposal: use thumbnail (foaf:thumbnail)
• license logo (eg Creative Commons)
  Decision: Deferred for discussion in broader community (eg Europeana, DPLA)

Allow metadata fields on content resources

Requested Feature: Ability to add metadata fields to content resources such as images, texts and other media. Currently this is not explicitly permitted in the specification. One convincing use case for this is to enable rights information, and basic descriptive information when available. Clients may choose not to display or process the information, but at the moment it's not legitimate to provide it.

Decision: Accepted

JSON-LD vs JSON for info file

Related tickets:

• #2 (@context URI should resolve)
• #3 (update website references to iiif.io domain)
• #5 (require CORS)

JSON-LD has a different media type than regular JSON (application/ld+json vs application/json). Which should the server provide with the info.json document? Metadata API is explicit that it should be ld+json, but may be json. Neither spec recommends .jsonld extension.

According to the JSON-LD specification (and clarification from the editors), processors receiving application/json documents should ignore @context and instead look for a link header pointing to a context document. Otherwise for application/ld+json, they should use @context and must ignore a header. At the moment we put @context in the document, but return application/json for compatibility with existing frameworks and systems.

See: http://lists.w3.org/Archives/Public/public-linked-json/2014Feb/0001.html

_Solution:_ You must support both application/json and application/ld+jsonld. Content will be the same, different mime types. URI is just info.json, and do content negotiation to get JSON-LD, otherwise assume JSON.

_Action:_ Rob to write the prose for this

Document position on ICC profiles

Color management came up more than once in Copenhagen.

Proposal: Drop [] form and only use URI Template

Having two forms of the URL syntax in section 2 is unnecessarily confusing. As URI Templates are a standard, we should just use them.

Scope of API (physical objects describable)

Documentation improvement:
The current draft of the metadata API talks in the introduction about supporting a “viewing environment for digitized physical objects”. From the intro and scope one might assume that information about the relationships between images of three dimensional objects are in scope, or even that perhaps three dimensional models might be in scope? However, the text that follows really assumes pretty-much two-dimensional physical objects with sides, folds, and relations (in 2d) to other objects. I think this mismatch should be addressed to make the spec more consistent. A simple example: what about 4 views of a sculpture? Are they just 4 “related” images or can we say more?

Decision:
NOT just about manuscripts or books, but about those things that can be described usefully as a sequence of 2d images (caveats galore) plus optional additional description.

Need additional use cases to include in the API documentation.
ACTION: Call for use cases on IIIF-Discuss

Resolve 400 vs 415

We should be more explicit about the 415 in section 4.5 if we think it's important to distinguish from other 400 errors codes. As just .../native is okay, and the server can do conneg, then 415 actually isn't the right error code, it should be 406 Not Acceptable.
Maybe we include a flowchart if we want to maintain the distinctions

Current: 415 - Format not supported
Alternatives: 406?
What about Conneg - 406 for that?
Spec says you may always return an image, even if in a different format.

Additional REST API Features

Decision: Incubate, possibly as an extension or annex to the spec. See here for a start.

Dereference of {server}/{prefix/}{identifier}

The current specification recommends, but does not mandate, that dereferencing the identifier without parameters should return the info.json document. What does this mean for the validator (it doesn't check) and level conformance (level 1 or 2?)

Should the specification be more explicit about what is required, and does it deserve to be better highlighted in the document? [Rob forgot to implement it, I bet others did too]

HTML for Humans, JSON for machines…

_Resolution_: Move to REST (PUT, POST, DELETE) discussion where we'll be talking about other sorts of interactions with this URI pattern.

integer "arithmatic"?

Related to #18 ...

The intro to section 4 states:
"All transformations are performed within the bounds of integer arithmatic [sic]. The rounding method is not specified."

And then goes on to talk about floating points. I don't really understand what this means other than that implementations shouldn't use floats? I suggest deleting it, or at least fixing the spelling of arithmetic.

Describe "sc:painting" better

Documentation Improvement: The specification was interpreted incorrectly recently as the reader did not understand the use of painting for transcription. The reader viewed transcription as metadata, not part of a facsimile. The specification could be clearer as to this common situation.

Notes:

• What does “painting” mean? Perhaps choose different vocabulary to denote “representation” or 1:1 relationship vs. other types of relationships
• add sub-classes?
• Perhaps rename painting as confusing, esp in Gallery use cases?

Decision:
Couldn't come up with a better motivation, so describe better and leave as painting (esp for backwards compatibility)

Collections of Manifests & Sub-Collections

Requested Feature: The ability to have collections of Manifests, and of other Collections. This allows a repository to advertise links to all of their available objects for harvesters or discovery platforms. The collection should have the same metadata fields as the Manifest, plus the links downwards to the Manifests and Collections. Manifests may appear in more than one collection, as there may not be a single hierarchy for the collections that a server publishes.

Proposed new URI patterns are:

{scheme}://{host}/{prefix/}collection.json                      -- top level collection
{scheme}://{host}/{prefix/}collection/{name}.json          -- sub-collections

Note that this prevents the existence of an object with identifier of "collection".

{
  "@context": "...",
  "@id": "http://example.org/iiif/collection.json",
  "@type": "sc:Collection",
  "label": "Top Level Collection for Example Org",
  "metadata": [{...}, {...}],
  "description": "Description of Collection",
  "attribution": "Provided by Example Org",
  ...

  "collections": [
    { "@id": "http://example.org/iiif/collection/part1.json",
      "@type": "sc:Collection",
      "label": "Sub Collection 1"
     },
     { "@id": "http://example.org/iiif/collection/part2.json", 
       ...
      }],

  "manifests": [
    { "@id": "http://example.org/iiif/book1/manifest.json",
      "@type": "sc:Manifest",
      "label" : "Example Manuscript"
    }, {...}, ...
  ]
}

Where "collections" maps to a new predicate "sc:hasCollections", "manifests" maps to "sc:hasManifests", both with range of rdf:List. Introduces a new class sc:Collection.
In Mirador, this would replace the current ad-hoc 'location' field in the manifest selection box.

Notes:

• Why a IIIF-specific solution for this?
  -- ease of implementation and integration. Not the same use case as ResourceSync (for example) as not everything, just hierarchy, which may have same manifest multiple times. Could link to other sites' manifests. Difference between small on-the-fly collection-building and full-server dump
• Need discussion to develop proposed solution and understanding of use-cases

Decision:

• Separate document linked from specification. (where?)

Editor's Proposal:

• Use format above

REST for Presentation API

Requested Feature: Resources, especially Annotations and AnnotationLists, should have RESTful services for creation, update and delete as well as the currently defined retrieval. The same has been requested for Images.

Example calls:

PUT /prefix/id/annotation/anno1.json         -- create/update named annotation
POST /prefix/id/annotation                         -- create server-named annotation
DELETE /prefix/id/annotation/anno1.json  -- delete named annotation
Theoretically, GET /prefix/id/annotation     -- retrieve all annotations for object 'id'
PUT/POST/DELETE on /prefix/id/list/ to manage lists directly
PUT/POST/DELETE on /prefix/ to create manifests
PUT/POST/DELETE on /prefix/collection/ to create collections

Decisions:

• No objections, separate spec
• More important than image REST API, esp for annotation creation
• Linked document
• Further discussion

Advertise Available / Optimal / Limited Sizes in info.json

Related issue: #6 (Canonical URIS)

info.json should list zero or more optimal sizes that the server makes available (e.g. thumbnails), either for optimal performance, or in lieu of supporting arbitrary sizes request (profile.json could indicate), or as a way to restrict the max resolution available to the client based on their rights? We already do the latter two, in a sense, with scale_factors.

"other_sizes" : [ "w,h",  "w,h", "w,h" ]

(need to fix the name, note oddness of x,y for this while we have width and height separately for other things… not sure of fix)

What does this mean? -Js

Only refers to the full image (not regions) and sizes thereof other than 'full' image.

_Mention in the specs_: Use case “full, medium, thumbnail” preview. Optimal for server delivery and caching.

The @context uri should resolve, and give a context document.

See #2

Follow Semantic Versioning

What do you think about following the Semantic Versioning?

Should info.json have different requirements at different compliance levels?

I'm thinking that capabilities (if applicable) and profile should be required for level 1

Labeling Links

Requested Feature: Ability to put a label on a link, so instead of displaying the url directly, a client can display the label, with a hypertext link to the URL. The labels should be specific to the usage, rather than global statements, such that the same URL can have multiple links for different reasons. Internationalization is also highly desirable.

Options:

1. Create a new "links" field with a list of {"href": uri, "label": label} blank nodes
2. Explicitly allow HTML in the value in metadata pairs

Non-Options:

1. Add label to resource in "related" -- this would apply the label universally, not just for the current context. Thanks open world graph.
2. Deprecate "related" -- a related object might be embedded rather than linked, for example a related video.

Editor's Proposal:
Option 2, allow HTML. This is more consistent with a display/layout API and doesn't require a new field.

Dynamic Annotation List Service

Requested Feature: A service profile that allows a manifest to record dynamically generated annotation lists, or lists of lists. The service could determine the user, and present further annotations that they have access to but are not part of the "official" facsimile.

The response would be an sc:AnnotationList, as currently defined, or like "otherResources" in the canvas.

Questions remain as to:
Should there be one service per canvas, and if so does the current spec not suffice?
Should there be one service per Manifest, and if so:
Should it be called once per Canvas (and if so, what's wrong with current spec beyond having to repeat the same field per Canvas?)
Should it be called once per Manifest, with the response containing annotations for all of the Canvases?
Are there additional parameters or requirements for the call that need to be added?

Notes:

• Agreed for further discussion

Action:

• Discuss on IIIF-Discuss

Proposal:

service: {
  "@id" : "http://.../service?canvas=asdf", 
  "profile" : "http://.../annotationListService"
} 

Geo-References in Metadata

Requested Feature: The ability to record a physical location that is associated with the resource. This could be either via lat/long, or via a URI, or (preferred) both.

Decision:

• Needs further clarification as to use cases to cover
• Needs a coherent proposal

bitonal sample image not in b & w

bitonal sample image (http://www-sul.stanford.edu/iiif/image-api/1.1/iiif-quality.2.png) seems to be in two tones, but not black and white. (Christopher)

Send Coyne a message

Once we have issues:

• #10
• #11
• #12
• #13
• #14
• #15
• #16
• #17
• #18

Closed

Native color: "The image is returned at an unspecified bit-depth."

Native color: "The image is returned at an unspecified bit-depth."

Shouldn't this be "at the original bit depth"? It seems like an implementer is free to downsample images retrieved this why, which seems unexpected.

_Simeon:_ “The image is returned in the server's default bit-depth for the format given.”

_Jon:_ "Yes, for the purposes of the API there should be no notion of 'originality'. Let's leave that for the proposed REST extension."

HTML IDs in spec

The HTML in this document repeats id attributes which is invalid HTML and makes it hard to create internal links to different sections (Christopher)

floating points allowable for percentage

OpenSeaDragon makes requests for size changes like this: pct:12.5. Can the spec be changed to state explicitly that floating point percentages are allowed?

ADD to intro of section 4 stating that floating points allowable for percentages