Version 2.0

[stephenwf]

Parser version 2

What's new?

In short, the parser now supports a wider variation of IIIF resources, such as the navPlace and textGranularity extensions and now normalizes further into the Annotation specification. It also includes parsing for IIIF Image services, allow you to query supported features from Image Services or construct IIIF Image URL requests.

Still remaining:

Additions

• Image 3 parsing / utilities Added Image 3 API #20
• hasPart extension Dereferencable labels #5 | Added hasPart support #23
• JSON-LD Framing as serialisation option Support JSON-LD framing  #10

Non-breaking - delayed features

• Immutability changes Immutable P3 #13
• Normalization of Image Services, Auth Services and Search Services (as they are official APIs)

Build

• Merge vite/vitest migration branch Vite + Vitest #22
• Add CodeSandbox CI Vite + Vitest #22
• Documentation
• Vault PR ready to accept these changes

Planned features

Normalization of Image Services, Auth Services and Search Services

This was something that was in very early versions, but became a difficult to maintain and stay correct - to support 2.1 and 3.0. A normalization step could upgrade the service to the latest version of the specification (even if it resolves to 2.1 for example) and Vault or other users could normalize and ingest the full image services into the store.

There are 2 approaches, splitting each into their own space in the store:

const result = normalize(p3Manifest);

result.entities.ImageService['https://example.org/image-serivce/info.json']; // An image service
result.entities.AuthService['https://example.org/auth-serivce/probe.json']; // An auth service
result.entities.SearchService['https://example.org/search-serivce/search']; // A search service

Or keeping them together in a generic Service

const result = normalize(p3Manifest);

result.entities.Service['https://example.org/image-serivce/info.json']; // An image service
result.entities.Service['https://example.org/auth-serivce/probe.json']; // An auth service
result.entities.Service['https://example.org/search-serivce/search']; // A search service

The first option would mean there may be a mix of references and nested items in resource.service but it does keep the similar formats together - the second option would add another layer of de-referencing to services which might add a bit of friction.

JSON-LD Framing as serialisation option

Currently the serialization uses code-as-configuration, with a format based on Object.fromEntries() format. As described in #10 this would allow you to pick and compose different resources together, a subset of their properties and have that generate a JSON-LD document out at the end. This format would be quite useful

Dereferenced label issue

As described in #5 there is an issue where multiple resources that are normalized (and then merged) may overwrite each other or have different labels and properties. Although this is unlikely to be fully resolved here, a first step may be to exposing the helper in the parser for merges together items for use outside, so that resources can avoid being overwritten.

Current changelog

Added

• Support for navPlace and textGranularity
• Fragment selectors in SpecificResources, strings and {id,type} References are now normalised, reducing the need to parse IDs to grab the ID/Type
• Added expand target helper, used internally for normalization (possibly useful for content state).
• New sub-package @iiif/parser/strict for fixing common mistakes in Presentation 3, with detailed feedback for implementors.
• New sub-package @iiif/parser/image-3 for parsing IIIF Image API and some helpers
• Test coverage across every IIIF Cookbook recipe, testing:
  • Parsing / Traversing the IIIF
  • Normalizing the IIIF correctly
  • Re-serializing the IIIF back to identical JSON
• New traversal option for SpecificResource
• New traversal option for GeoJson (e.g. from the navPlace extension)
• New storing of Services when normalizing ¹

Fixed

• [presentation-2] startCanvas property on Sequences are now added to the Manifest when converting
• Fixed handling Specific resources where the source is only string (inferring the correct type from the context)
• Serializing Presentation 2 resources without items
• Bug where AV canvases would have height and width of 0 when serializing
• Bug where custom @context on Manifest was not retained during serialization
• Bug where Content Resources did not keep extra properties when serializing (e.g. value or geometry)
• Bug where serialization may sometimes include UNSET keyword.

Removed

• posterCanvas - hangover from pre-3.0, this will be ignored
• logo on non-provider resources - hangover from pre-3.0, these will be ignored²
• motivation field on non-Annotation resources (bug)
• Traverse.traversePosterCanvas() is removed (now Traverse.traverseLinkedCanvases())

Changed

• range.items[] is now normalised to either Reference<'Range'>³ or SpecificResource<Reference<'Canvas'>>⁴
• manifest.start is now normalised to a SpecificResource<Reference<'Canvas'>>

Footnotes

1. This does not replace the inline services with references, instead it's a parallel store of normalized services. Editing tools will have to update both. This moves the problem of multiple services with different structures and fields to the user. The normalized structures will be specifically useful for loading Image services progressively in a store without affecting the serialisation of the IIIF. ↩

2. These properties were added to the specification pre-3.0 and then later removed. ↩

3. A Reference<T> has the shape: { id: string, type: T } and is usually narrowed to one or more types ↩

4. SpecificResource is defined by the W3C Annotation specification, but in short you can access the original reference by accessing specificResource.source ↩

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 5974107:

Sandbox	Source
React	Configuration
simple-parser	Configuration

[stephenwf]

Bug with ImageService2 when converted to Presentation 2 (profile is incorrect)