Skip to main content

IIIF-metadatahandboek

IIIF-Metadata

Overzicht

Metadata en IIIF?

Naast de keuze van de viewer is het al even belangrijk om op voorhand af te wegen welke metadata je op welke manier ter beschikking wil stellen. IIIF-viewers zijn immers niet gebouwd om zoveel mogelijk metadata ter beschikking te stellen, maar dienen prioritair om digitale beelden zo goed mogelijk te presenteren.

Erfgoedinstellingen willen vaak  extra metadata ontsluiten via een bijkomende contentlaag buiten de IIIF-viewer. Het is in die bijkomende contentlaag dat de kunstwetenschappelijke metadata uit het collectiebeheersysteem ontsloten wordt. Speciaal of extra veel metadata aanmaken voor IIIF-viewers is niet aangewezen, het is wel aan te raden om bestaande metadata zoveel mogelijk te hergebruiken.

Het is dus belangrijk goed af te wegen welke metadata je wil aanbieden binnen of buiten de IIIF-viewer. Metadata die je via de viewer wil presenteren blijft best beperkt tot beschrijvende metadata (objectgerelateerde metadata nodig om het beeld te identificeren en te kaderen binnen een groter geheel: een paneel binnen een veelluik, een pagina binnen een boek, een prent binnen een reeks, …), specifieke beeldgerelateerde metadata (de fotograaf, …), juridische metadata (hergebruiklicenties) en eventueel ook linkende metadata. 
Administratieve metadata (zoals de schenker, bruikleengeschiedenis,,…), veiligheidsgerelateerde metadata (het aankoopbedrag, de bewaarplek in het depot, de plaats waar het object is opgesteld, …) en conservatorische metadata (info over een restauratie, eventuele schade of bewaarcondities) horen volgens ons niet thuis in een IIIF-viewer. We komen hier later bij ‘metadata gebruiken en verwerken’ nog verder op terug.

Metadata en de IIIF Presentation API

Binnen IIIF is alle informatie eigenlijk metadata, voornamelijk binnen de IIIF Presentation API, met daarbij o.a. beschrijvende metadata (zoals bijvoorbeeld de kunstenaar of auteur, de titel van het werk, de datum van creatie,  de korte inhoud, de afmetingen, …), fotografische reproducties, beeldgerelateerde metadata (zoals bijvoorbeeld de fotograaf, de copyrightstatus en de hergebruiklicentie),  en linkende metadata voor externe bronnen (bijvoorbeeld links naar een webpagina over een object, pdf-versie van een boek, persistente URI’s, eigen gecreëerde persistente identificatoren (PID’s), koppelingen met externe authorities of rechtenverklaringen, Creative Commons-licenties, …).

Om metadata te tonen in een IIIF-viewer heb je een specifieke API nodig die data ophaalt uit de IIIF-bron.
De Image API stelt je in staat om afbeeldingen uit te wisselen, maar deze Image API levert, behalve een rechtenelement via de info.json, niet echt beschrijvende metadata aan.
Oorspronkelijk voorzag de IIIF-community een aparte Metadata API, maar sinds 2013 is deze vervangen door de Presentation API (huidige versie 3.0.0). Via de Presentation API kan je wel beschrijvende of structurele metadata delen en op die manier dus alle metadata meegeven die noodzakelijk zijn om een artefact eenduidig en logisch te presenteren.

Voor het gebruik van de Presentation API is het noodzakelijk om een gestructureerd bestand (manifest) te maken dat verwijst naar een beeld in de Image API. Als de structuur van complexe objecten en metadata in het manifest opgenomen worden, kan je bijvoorbeeld gedigitaliseerde pagina’s van een boek in de juiste volgorde tonen en zo door het boek bladeren, zoals je in het originele boek zou kunnen doen.
Manifesten kunnen statisch (door zelf te schrijven) of dynamisch (gegenereerd via een geautomatiseerd proces)  worden aangemaakt. De gegevens die je nodig hebt om een manifest te maken kunnen afkomstig zijn van verschillende systemen binnen je omgeving (uit het collectiebeheersysteem, het DAM-systeem, …). 

Opmerking: Voor alle (nieuwe) toepassingen of applicatie-versies dienen de meest recente IIIF-specificaties gebruikt te worden. Oude versies van IIIF-specificaties worden bewaard ter referentie. Voor manifests opgemaakt in funcite van (ver)ouder(d)e applicaties is er geen garantie van onderhoud en dus toonbaarheid in nieuwe versies van die applicaties.
Bij de verdere bespreking proberen we zoveel mogelijk gebruik te maken van en te verwijzen naar IIIF-versie 3.0.0. Bij sommige voorbeelden (zie "Voorbeelden") kan een nog eerdere IIIF-versie (2.1.1) gebruikt zijn, afhankelijk van wanneer het project of het manifest werd gemaakt. Momenteel ondersteunen nog niet alle viewers de nieuwe functies van versie 3.0.0. Verdere ontwikkeling is bezig om dit op termijn te verbeteren. We proberen bij "Voorbeelden" zoveel mogelijk de verschillende versies, zowel 2.1.1 als 3.0.0 te gebruiken.
Volgende documenten zijn een aanvulling op de IIIF Image & Presentation API-specificatie, versie 3.0, en beschrijven de wijzigingen die aangebracht zijn in versie 3.0.0 t.o.v. vorige versie 2.1.1, met inbegrip van die welke achterwaarts (backwards) onverenigbaar zijn met versie 2.1.1. 
Change Log: IIIF Image API 3.0  en  IIIF Presentation API 3.0.  Nog meer info over de API-versies.

Structuur en overzicht binnen de IIIF Presentation API 3.0

We verwezen eerder al naar een manifest, het document dat alle informatie bevat die nodig is om de hele bron en alle geralteerde info goed en logisch te presenteren. Wat is de plaats van het manifest in de hele IIIF-opstelling?

De Presentation-API biedt een model om een samengesteld object (via het Manifest) en de afzonderlijke delen van het object (Canvas) te bundelen en ervoor te zorgen de juiste pixels of het juiste moment worden opgevraagd en weergegeven. Elke weergave kan verwijzen naar afbeeldingen, audio, video en andere bronnen. Een samengesteld opbject kan ook secties hebben: een boek kan hoofdstukken van meerdere pagina's bevatten of een toneelstuk kan worden onderverdeeld in akten en scènes (Range) en je kan ook collecties maken (Collection). Deze brontypes (resource-types) vormen samen met hun eigenschappen (properties), de IIIF Presentation API.

Het onderstaande schema geeft een overzicht van de brontypes (of klassen) die in de IIIF-specificatie gebruikt worden.
Hier vind je meer uitgebreide info en uitleg om elk brontype in detail te bestuderen.

Data Model

Structuur via gedefinieerde brontypes:
Collection: ordent manifesten in groepen en deelt ze via een enkele url
Manifest: beschrijving van de structuur en eigenschappen van een object
Canvas: virtuele container/locatie voor inhoud (afbeelding object), cfr. PowerPoint-dia

Range: biedt navigatie doorheen het object door het op een logische manier te groeperen/ordenen

Extra brontypes:
Annotation page: verzamelen en ordenen van lijsten met notities/annotaties
Annotation Collection: geordende lijst van annotatiepagina’s
Annotation: associeert inhoud met canvas
Content: afbeelding, tekst, geluid van het originele object/artefact/bron 

Metadata - Broneigenschappen

De meeste eigenschappen kunnen worden geassocieerd met elk van de beschreven brontypes en kunnen meer dan een waarde hebben. Zo is het label van een Manifest de titel  van het object, terwijl het label van een Canvas een titel of benaming is voor een specifiek beeld. Er zijn ook expliciete aanbevelingen over welke brontypes (klassen) welke eigenschappen moeten hebben. Je kan deze terugvinden in een uitgebreid schematisch overzicht.

Eigenschappen zijn dus soms verplicht of niet (must/must not), zijn vereist (required), zullen of zullen niet (shall/shall not), zouden moeten of niet (should/should not), zijn aanbevolen (recommended), mogen (may) of zijn optioneel (optional). Ze worden, zowel hier als in iiif.io-documenten, geïnterpreteerd zoals beschreven in RFC 2119. RFC2119 is een standaard voor zogenoemde requirement levels, trefwoorden die op een duidelijke manier aangeven wat wel of niet noodzakelijk is binnen een specifieke standaard. 

Bijvoorbeeld bij ‘label’:
het label is de titel van het object ("Example Object Title") in het Engels ("en"):    { "label": { "en": [ "Example Object Title" ] } }

Een Collectie en een Manifest moeten (must) een ‘label’ hebben met ten minste 1 vermelding. Een Canvas, een Range en een Annotation Collection zouden (should) een ‘label’ moeten hebben met ten minste 1 vermelding. Een Content-bron en andere types bronnen mogen (may) een ‘label’ hebben met ten minste 1 vermelding.

Opmerking: zoals eerder ook al vermeld is er een verschil tussen versie 3.0.0 en vorige versies (meestal 2.1.1). Bij gebruikte eigenschappen zijn er bijvoorbeeld enkele benamingen gewijzigd. We hebben in de uitleg hieronder, vooral bij vaak gebruikte eigenschappen, al enkele wijzigingen aangeduid bv. ‘summary’ > ‘description’ in v2. (uitgebreide info)

Beschrijvende eigenschappen
Beschrijvende eigenschappen beschrijven of vertegenwoordigen de bron/het artefact/het object waarmee ze geassocieerd zijn en worden ter duiding weergegeven aan de gebruiker. Beschrijvende eigenschappen zijn onder meer:

  • label: de naam of de titel van het object. metadata: een geordende lijst met beschrijvingen die aan de gebruiker getoond moeten worden, via paren als ‘label’ en ‘value’. Bijvoorbeeld: ‘label’: Kunstenaar’ en ‘value’: "James Ensor (1860-1949)".
  • summary > description in v2: een korte samenvatting of beschrijving van het object.
  • requiredStatement > attribution in v2: een korte tekst die moet worden weergegeven o.a. voor auteursrecht, de collectiehouder, fotograaf,…
  • rights > license in v2: een link (URL) naar een externe bron die de (hergebruik)licentie- of rechtenverklaring aangeeft. Hiervoor moet Creative Commons of RightsStatements.org gebruikt worden, tenzij de specifieke licentie met de kunstenaar online raadpleegbaar is.

Technische eigenschappen
Technische eigenschappen beschrijven de technische kenmerken van de bronnen en worden gewoonlijk door de viewer verwerkt om te begrijpen hoe de bron moet worden weergegeven o.a. 

  • id > @id in v2: de effectieve link of URI die de bron identificeert.
  • type > @type in v2: type of klasse van de bron. Dit kan o.a. beeld, tekst, geluid of video zijn.
  • format: het specifieke mediatype (vaak een MIME-type genoemd) voor de bron, bijvoorbeeld image/jpeg.
  • language: de taal of talen die gebruikt worden in de inhoud van deze externe bron.

Linkende eigenschappen
Linkende eigenschappen zijn verwijzingen of links tussen bronnen, opgesplitst in externe en interne links:

  • externe links waarbij het gelinkt object zich buiten de IIIF-ruimte bevindt o.a.
    • homepage > related in v2: link naar een webpagina van het object.
    • service: link om extra informatie of functionaliteit te krijgen voor het gebruik van de bron.
    • seeAlso: link naar een machineleesbaar bestand dat het object beschrijft, bijvoorbeeld een XML-export van het record uit het collectiebeheersysteem.
  • interne links waarbij het gelinkt object een IIIF resource is o.a. partOf, start, supplementary, …
    • partOf > within in v2: link naar een IIIF-bron die deze bron bevat, kan gebruikt worden voor een object dat behoort tot een collectie. Bijvoorbeeld een prent uit een prentenreeks, een paneel uit een retabel,…
    • start > startCanvas in v2: link naar een Canvas of deel ervan om de gebruiker het beginpunt (de start) van de bron te tonen.
    • supplementary: link van een ‘Range’ naar een Annotation Collection die aanvullende annotaties van bronnen voor die ‘Range’ bevat. Voorbeeld 1: De ‘Range’ vertegenwoordigt delen van een manuscript die zijn getranscribeerd of vertaald, terwijl er andere delen zijn waaraan nog moet worden gewerkt. Voorbeeld 2: De ‘Range’ vertegenwoordigt een aantal opeenvolgende bladen uit een schetsboek van George Minne die kunnen worden gelinkt aan een specifiek beeldhouwwerk van George Minne, terwijl andere bladen uit dat schetsboek niet aan dat specifieke beeldhouwwerk kunnen worden gelinkt.

Structurele eigenschappen
Structurele eigenschappen definiëren de structuur van het object om het mogelijk te maken om ‘child recources in parents’ op te nemen bv. Canvas in een Manifest of Manifest in een Collection. Meestal wordt items gebruikt, maar er zijn 2 speciale gevallen voor verschillende soorten structuren.

  • Items: vastleggen van de volgorde waarin ‘child resources’ voorkomen binnen ‘parent’ bronnen, zoals Collection of Manifests binnen een parent Collection of Canvases binnen een Manifest. Een voorbeeld zou kunnen zijn: Een gedrukte encyclopedie (parent bron) kan gezien worden als een collectie van boeken (child resources). De encyclopedie (Collection) heeft verschillende boeken (manifesten) van de verschillende jaargangen (items). Elk boek (manifest) heeft verschillende pagina's van een specifieke jaargang (items). Elke pagina wordt op een apart canvas weergegeven.
  • structures: structuur van een object dat als een Manifest wordt weergegeven, kan worden beschreven met behulp van een hiërarchie van Ranges. Bijvoorbeeld: Ranges kunnen worden gebruikt om de ‘inhoudsopgave’ van het object te beschrijven of andere logica’s of structuren waarmee de gebruiker kan navigeren buiten de volgorde die door de eigenschap ‘items’ van het Manifest wordt opgegeven.
  • annotations: geordende lijst van Annotation Pages die commentaar of andere Annotaties over deze bron bevatten, los van de Annotaties die worden gebruikt om de inhoud op een Canvas te duiden. Bijvoorbeeld: overkoepelende notities over de restauratie van een manuscript terwijl het canvas telkens maar een pagina van het manuscript weergeeft en bij dat canvas enkel de transcriptie van de middeleeuwse tekst als annotatie is terug te vinden.

Annotaties
Annotaties bestaan steeds uit 3 karakteristieken: target, body en motivation (soms ook purpose genoemd):

  • Target: het item (of deel daarvan) waarop de annotatie betrekking heeft.
  • Body: de waarde van de annotatie zelf. Dit kan zowel een tekst (bvb een opmerking), een afbeelding (bvb een detailfoto van een schadegeval) of zelfs audio of video zijn.
  • Motivation (in sommige gevallen purpose): dit geeft de verhouding tussen de annotatie en het target weer. De 2 mogelijke waarden hiervoor zijn ‘painting’ en ‘supplementing’. ‘Painting’ wordt gebruikt om de hoofdafbeelding aan te duiden (gezien in de Presentation API v3 de afbeelding ook als een annotatie gezien wordt). Alle andere types annotaties zijn van het type ‘supplementing’, aangezien zij niet op zichzelf staan, maar enkel meer info geven over de hoofdafbeelding.
     

Metadata gebruiken en verwerken

Om te weten welke metadata je best gebruikt en hoe je deze het best verwerkt, gaan we nog wat dieper in op het Manifest, de sleutel voor het gebruik van IIIF. 

De definitie van een IIIF-manifest luidt als volgt: Een Manifest is een algemene beschrijving van de structuur en de eigenschappen van het samengestelde object. De Manifest-bron vertegenwoordigt meestal een enkel object en elk intellectueel werk of deelwerk belichaamt in dat object. Het bevat met name beschrijvende informatie, informatie over rechten en links gerelateerd aan het object. Het bevat de canvassen die moeten worden weergegeven als weergaven van het object (hoe m.a.w. een object, zoals een boek, een beeld, een complex kunstwerk of muziekalbum, moet worden gepresenteerd). Het bevat dus voldoende elementen voor de beheerder van de content om deze content samen te vatten en deze op een logische wijze aan de gebruiker te laten zien.
Je kan extra info met een voorbeeld manifest terugvinden op de IIIF-website en ook op deze demosite bij onze “Voorbeelden”.

Het manifest is dus de machineleesbare samenvatting van wat men wil tonen in een viewer en wordt geïmporteerd in de IIIF-viewers en eventueel andere IIIF-compliant tools. De IIIF-viewers weten wat ze moeten doen met de metadata die in het manifest gestructureerd zijn volgens de IIIF-regels en vertalen deze informatie in zo een gebruiksvriendelijk mogelijke kijk- en tegenwoordig zelfs luisterervaring.Het manifest zelf is toegankelijk of kan gevonden worden via een URL die verwijst naar een online document, geschreven in een formaat dat JSON-LD heet (JavaScript Object Notation for Linked Data), dat door een IIIF-applicatie kan worden gelezen en weergegeven.
Databases met alle beschikbare manifesten wordt ook wel eens IIIF-stores genoemd. In het VKC-ecosysteem is Imagehub de IIIF-store.

Welke metadata in een manifest gebruiken?

Zoals eerder reeds aangegeven bij de keuze van de IIIF-viewer moet je niet alleen zelf bepalen wat voor jou de beste manier is om manifesten te maken (manueel of via een script), maar ook wat jij (of je instelling) aan content via het manifest wil mee- en weergeven. We herinneren je er nog eens aan: weeg goed af wat je via de IIIF-viewer aan content wil meegeven en wat je via andere contentlagen wil publiceren. We raden je aan om enkel de beeldgerelateerde content in het IIIF-manifest (en bijgevolg via de IIIF-viewer) te publiceren, samen met die content die noodzakelijk is om het object en de maker zelf te identificeren.

We hebben eerder al vermeld dat sommige broneigenschappen of metadata volgens de Presentation API specificaties verplicht, aanbevolen of optioneel zijn. Zo moet een manifest een ‘label’ hebben (MUST have/required) en is een ‘summary’ aanbevolen (recommended). Deze bepalingen vind je nog eens terug in dit schematisch overzicht.

Daarnaast kan of moet je volgens de beschikbare hoeveelheid metadata dus een aantal (vrije) keuzes maken. We probeerden in kaart te brengen welke metadata internationale musea en andere instellingen vaak of zelden gebruiken. De praktijk verschilt naargelang het museum of de instelling. Er is geen uniforme praktijk. Sommige musea of instellingen publiceren veel metadata in het manifest, andere weinig. Een ‘gulden middenweg’ lijkt ons aangewezen.  
Er is evenmin een lijn te trekken in de gepubliceerde metadata naargelang het soort werk (boek, schilderij, film, …). Als er eenduidige verschillen zijn, dan lijken die ook zeer logisch. Zo wordt bij geschreven werken meestal de “language” (bv. Latijn) vermeld, wat je bij schilderijen uiteraard niet ziet.

Een kort overzicht:
   - Meest voorkomend/bijna altijd: label/title, artist, description (tekst of soms link naar externe file),
     date, object - inventory number, rights statements, copyright (license, attribution, logo), links (related, within)
   - Soms: medium, genre, material, dimensions, place created, collection, culture - provenance, seeAlso
   - Zelden: markings, inscriptions, signed, more information, item conditions, digitized by, ...

We opteren om in de uitgewerkte voorbeelden (zie Voorbeelden) volgende metadata te verwerken in het manifest en de IIIF-viewer(s):

  • Label/Title – Label/Titel
  • Artist – Kunstenaar
  • Date – Datum
  • Inventory or object number – Inventaris- of registratienummer
  • Summary > Description v2 – Beschrijving
  • Photographer - Fotograaf
  • RequiredStatement > Attribution v2/Collection > Attributie v2/Collectie + eventueel Citation/Bronvermelding. In onze uitgewerkte voorbeelden is zo’n bronvermelding als extra toegevoegd o.a. om via de beeldbeherende instelling de originele bestanden van gebruikte werken te bestellen.
  • Rights > License v2

Samengevat zou je kunnen stellen dat het belangrijk is dat via het manifest volgende vragen kunnen worden beantwoord.
Bevat het manifest voldoende informatie
- om het object in de presentatie eenduidig te identificeren?
- om het object in de presentatie logisch te presenteren?
- voor het rechtsgeldig hergebruik van de presentatie?

Hoe maak je een manifest?

De meeste manifesten worden machinaal aangemaakt of geschreven, maar je kan het ook handmatig doen.

Machinaal: Als je een grote hoeveelheid manifesten voor gelijkaardige artefacten (bijvoorbeeld alle schilderijen uit de collectie) moet maken is het gebruik van een machinaal systeem aangewezen. Bij de machinale aanmaak worden via een script metadata uit het collectiebeheersysteem en DAM opgehaald en op een uniforme wijze aan een typemanifest toegevoegd. Door deze machinale productie van manifesten win je ongetwijfeld veel tijd. Het enige wat je moet doen is een typemanifest voor een specifiek type artefact aanmaken. Spreek hierover je IT-dienst/ontwikkelaar aan, waarschijnlijk zal je bepaalde systemen en workflows moeten installeren, omdat specifieke kennis of maatwerk misschien wel vereist is. Wij kunnen, indien gewenst, ook wel enig advies geven.

Waarom zou je een manifest dan “handmatig” aanmaken als alles volledig automatisch kan gebeuren? Het lijkt ons eerst en vooral zeer zinvol om bij wijze van studie een aantal manifesten zelf aan te maken. Het is een ideale manier om te begrijpen hoe IIIF werkt.

Anderzijds zullen de typemanifesten voor specifieke artefacten uit je collectie geen bevredigende presentatie opleveren. Een manifest voor een eenvoudig schilderij zal waarschijnlijk ook wel werken voor een eenvoudige tekening of prent. Maar datzelfde manifest zal geen gebruiksvriendelijke presentatie opleveren voor bijvoorbeeld een veelluik, laat staan voor een schetsboek of een manuscript. Wanneer er complexe artefacten in het spel zijn zal je een specifiek manifest moeten schrijven zodat het artefact op een logische en volledige wijze via een IIIF-viewer kan worden gepresenteerd.

Bij Voorbeelden worden een aantal complexere manifesten gedemonstreerd. Je kan deze voorbeelden als inspiratie gebruiken om zelf aan de slag te gaan via ‘copy/paste’. Bij complexe artefacten denken we graag met je mee. Neem dan gerust contact op met de VKC-IIIF-beeldbeheerder.

Een andere, maar geenszins eenvoudige manier is om zelf code te schrijven via een tekst- of (online) json-editor. Er zijn ook verschillende bibliotheken voor het schrijven van code, die je, in een taal die je past, hiervoor kunt gebruiken. Dit vereist wel enig technisch inzicht en is lang niet geschikt voor iedereen, maar het is wel een mogelijkheid die een flexibele aanpak toelaat.

Een laatste mogelijkheid om manifesten te genereren is het gebruik van een IIIF-manifest-editor. Het is een lichtgewicht, webgebaseerd hulpmiddel om bestaande IIIF-manifesten te manipuleren en nieuwe te maken zonder de JSON-LD (het semantisch formaat van JSON, LD staat voor Linked Data, JSON is een standaard voor objectbeschrijving) rechtstreeks te moeten kennen of bewerken. Hiermee kan je afbeeldingen en metadata importeren, bekijken, bijwerken en exporteren met behulp van de IIIF-API’s. Deze relatief gebruiksvriendelijke tool bespreken we uitgebreider bij Tools.

Ten slotte wil je waarschijnlijk ook controleren of het manifest dat je hebt geschreven ook effectief werkt. Om de inhoud van een manifest te controleren, kun je de online Presentation API Validator van het IIIF-Consortium of een JSON-validator voor json-bestanden gebruiken.

Andere te verkennen tools:
   - Andere validators
   - Tools om manifests te schrijven via een script
   - Hulpmiddelen voor het presenteren van IIIF-materiaal voor o.a. tentoonstellingen en eventueel andere functies zoals storytelling.

This work is licensed under CC BY 4.0 - Vlaamse Kunstcollectie/Karin Vanderpoorten