Skip to content
archAIc
Blog

IIIF

archAIc is a first-class IIIF citizen. Every libro is a Presentation 3.0 Manifest, every page is a Canvas, every transcription line is a Web Annotation, every place mentioned in the libro shows up on a map via the navPlace extension. Any IIIF viewer (Mirador, Universal Viewer, Tify, Theseus) opens an archAIc libro without custom plugins.

What archAIc speaks

Section titled “What archAIc speaks”
SpecEndpointStatus
Presentation API 3.0GET /v1/iiif/{collection}/{libro}/manifest.jsonStable
Image API 3.0Cantaloupe sidecar at /iiif/3/{id}/…Stable
Collection 3.0GET /v1/iiif/collection.json, GET /v1/iiif/{collection}/collection.json, GET /v1/iiif/group/{id}.jsonStable, nested
AnnotationPage (transcription)GET /v1/iiif/{c}/{l}/{p}/annotation-page.jsonStable
AnnotationPage (entities)GET /v1/iiif/{c}/{l}/{p}/entities-annotation-page.jsonStable
AnnotationCollectionGET /v1/iiif/{c}/{l}/annotation-collection.jsonStable, paginated, one AnnotationPage per canvas
Content Search 1.0GET /v1/iiif/{c}/{l}/search?q=…Stable
Content Search 2.0GET /v1/iiif/{c}/{l}/search/v2?q=…Stable
Content State 1.0inline in ?iiif-content=… deep linksStable
Change Discovery 1.0GET /v1/iiif/activity/all-changes.json + /activity/page/{n}Stable
navPlace extensionnavPlace block on Manifest and RangeStable
Auth API 2.0three-endpoint facade over the SSO sessionRoadmap, gated on SSO landing
Image API 4.0informational track, no work scheduledRoadmap

The whole surface is gated on cfg_setting.iiif.enabled. Disabling returns 404 on every /v1/iiif/* route.

archAIc concepts mapped to IIIF resources

Section titled “archAIc concepts mapped to IIIF resources”
archAIcIIIF resource
CollectionCollection
Libro (volume)Manifest
Folio (scanned page)Canvas
DLU (logical document)Range (with optional FragmentSelector for sub-page boundaries)
Transcription lineAnnotation on the transcription AnnotationPage
Entity mention (person, place, organisation)Annotation on the entities AnnotationPage
Place with coordinatesFeature in the manifest’s navPlace FeatureCollection
Cover / binding photographaccompanyingCanvas on the Manifest
Audit log entryActivity in the Change Discovery OrderedCollection

The DLU tree surfaces as the manifest’s structures block. Mirador renders it as a clickable navigation tree on the left of the viewer, so opening an archAIc libro shows the act-by-act structure of the volume immediately, not just the page sequence.

A manifest at a glance

Section titled “A manifest at a glance”
{
  "@context": "http://iiif.io/api/presentation/3/context.json",
  "id": "https://archaic.example/v1/iiif/rmcr/1/manifest.json",
  "type": "Manifest",
  "label": { "es": ["Libro 1"] },
  "items": [ /* canvases */ ],
  "structures": [ /* Ranges, one per DLU, nested */ ],
  "annotations": [ /* manifest-level entity AnnotationCollection */ ],
  "navPlace": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "label": { "es": ["Santiago de Compostela"] },
          "target_canvas": ".../canvas/47"
        },
        "geometry": { "type": "Point", "coordinates": [-8.544, 42.880] }
      }
    ]
  },
  "homepage": [ { "id": "https://archaic.example/dipuCoru/index.php?col=rmcr&book=1", "type": "Text", "label": { "en": ["View in archAIc"] }, "format": "text/html" } ],
  "rendering": [
    { "id": ".../export?format=ead-xml",     "type": "Dataset", "label": { "en": ["EAD-XML"] },     "format": "application/xml" },
    { "id": ".../export?format=eac-cpf-zip", "type": "Dataset", "label": { "en": ["EAC-CPF ZIP"] }, "format": "application/zip" },
    { "id": ".../export?format=atom-csv",    "type": "Dataset", "label": { "en": ["AtoM CSV"] },    "format": "text/csv" }
  ],
  "seeAlso": [
    { "id": ".../dlu/{id}.json", "type": "Dataset", "label": { "en": ["ISAD(G) JSON"] }, "format": "application/json" }
  ]
}

Clicking a navPlace marker pans the viewer to the page where the first mention of that place was made, and highlights the line. The geospatial side and the textual side stay synchronised through the target_canvas property.

Entity annotations

Section titled “Entity annotations”

Persons and organisations land on a separate AnnotationPage per canvas, sibling of the transcription AnnotationPage. Each entity mention becomes one Annotation with motivation: ["tagging", "identifying"]. The identifying body points at archAIc’s Linked Art record for that entity, so a viewer that follows the link gets the canonical name, alt names, biographical dates, and the full mention list across the corpus.

The same no-anchor-no-entry rule applies as everywhere else in archAIc: an entity without (page, line) mentions is filtered out at read time. Every Annotation that ships has line-bbox provenance.

Content State 1.0

Section titled “Content State 1.0”

Content State lets you encode the viewer state (which canvas, which search hit, which selector) into a base64 deep link. The share endpoint:

GET /v1/iiif/share?canvas={canvas_id}&q={query}&hit={n}

returns a Mirador URL with ?iiif-content=… already attached. Paste the URL anywhere; the recipient lands on the exact same canvas, with the same search active, at the same hit. Critical for sharing search results in a report or a colleague’s pager-duty channel.

Change Discovery

Section titled “Change Discovery”

The Change Discovery endpoint emits an ActivityStreams 2.0 OrderedCollection at GET /v1/iiif/activity/all-changes.json, paginated by /v1/iiif/activity/page/{n}. Each entry is a Create, Update, Delete, Add, or Move activity sourced from the engine’s audit log. DPLA, Europeana, BnE federated catalogs, and any other IIIF aggregator can harvest a deployment with a single poll URL.

Validation

Section titled “Validation”

archAIc ships a two-layer validation strategy:

  • Layer A: structural unit tests in gd-iiif. Required fields, type enums, URL shape conventions, cross-field invariants. Runs on every cargo test.
  • Layer B: the upstream Python iiif-presentation-validator wrapped in tests/iiif/validate.sh. Runs on demand against any manifest URL or fixture.

The community validator at https://presentation-validator.iiif.io/validate?url=… is documented for ad-hoc spec checks; CI does not call it.

References

Section titled “References”