iiif / api Goto Github PK
View Code? Open in Web Editor NEWSource for API and model specifications documents (api and model)
Home Page: http://iiif.io/api
Source for API and model specifications documents (api and model)
Home Page: http://iiif.io/api
There's a comma missing after the qualities property [in the JSON example]
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.
We call it capabilities ... so the key should be capabilities, not features.
No, was the decision, but the spec should be clear about it
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
Need to get to the bottom of this, but there is at least one case, possibly two:
Should this be reflected in info.json?
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
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
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'.
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"
What do you think about following the Semantic Versioning?
... 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)
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"
}
Now with the features response, there are 3 possible requests. Need to change intro to section 2.
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.
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.
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
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.
Implementation logic (possible):
See this gist for how the new info.json might look.
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)
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.
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:
Editor's Proposal:
{
"@id": "http://example.org/iiif/book1/canvas/f1r-curtain.json",
"@type" : "sc:Canvas",
"viewingHint" : "non-paged",
"height" : 1200,
"width" : 800,
"images" : [...]
}
Decision: Incubate, possibly as an extension or annex to the spec. See here for a start.
... Does it have to be a constant color?
_Solution:_
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.
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.
It would be nice to have a script that
It won't be a pretty thing, but it should make it easier to do quick releases to fix typos, etc.
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:
Decision:
Couldn't come up with a better motivation, so describe better and leave as painting (esp for backwards compatibility)
... 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
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.
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:
The HTML in this document repeats id attributes which is invalid HTML and makes it hard to create internal links to different sections (Christopher)
I'm thinking that capabilities (if applicable) and profile should be required for level 1
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:
Action:
Proposal:
service: {
"@id" : "http://.../service?canvas=asdf",
"profile" : "http://.../annotationListService"
}
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:
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.
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:
{"href": uri, "label": label}
blank nodesNon-Options:
Editor's Proposal:
Option 2, allow HTML. This is more consistent with a display/layout API and doesn't require a new field.
Related tickets:
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
Color management came up more than once in Copenhagen.
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:
Decision:
Editor's Proposal:
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:
Having two forms of the URL syntax in section 2 is unnecessarily confusing. As URI Templates are a standard, we should just use them.
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
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."
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.
You did it already in the demo. The second option for regions in the demo is what I call gravity:
1400,1200,2500,1075
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?
See #4
However, older versions (< 1.2) of the spec should keep the old library.stanford.edu namespace.
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.
Metadata spec should be markdown like image api.
See #2
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.
See #4
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.