- Dit is een levend document -

Handleiding digitaal delen opencultuur agenda data

Inleiding

Digitaal delen van agenda data voor experiment en innovatie

Als de culturele sector erin slaagt om de metadata rond zijn evenementen en registraties op een uniforme manier te delen, biedt dat veel mogelijkheden voor experiment en innovatie. Daarom willen we in openheid een standaard ontwikkelen.

Agenda of kalenderdata wordt op dit moment op verschillende manieren gepubliceerd op een online agenda. In deze handleiding staat een manier om kalenderdata aan de bron te publiceren op een manier die voor machines toegankelijk is en eenvoudig opgehaald kan worden via haar URL en getoond kan worden in andere agenda’s, bijvoorbeeld die van een ander podium. Ook maakt dit het mogelijk om de kalenderdata van meerdere instellingen op te halen en samen te brengen in een agenda met een bepaald thema (bv debatcentra) of locatie (bv culturele events in Limburg).

Een decentrale aanpak voor behoud van autonomie

De technische inrichting moet uitgaan van een decentrale architectuur, zodat de autonomie van de instellingen zo groot mogelijk blijft en het niet afhankelijk wordt van één centrale organisatie;
^[1]

Wij willen dat de cultuursector zelf kan kiezen met wie een relatie aan te gaan. Het verschil met een centrale aanpak is dat er meer autonomie en keuzemogelijkheid kan ontstaan op een decentrale wijze. Niet alle podia hetzelfde, hebben verschillende behoeftes, mogelijkheden en gebruiken andere oplossingen. Het ene podium heeft een volledige agenda op zijn eigen website, een andere doet publiceert vooral aankondigen via sociale media zoals Facebook, Instagram of TikTok.

^[1]

Bestaande open standaarden en onze voorkeur

De gebruikte standaard wordt bij voorkeur niet nieuw ontwikkeld; in plaats daarvan worden bestaande standaarden in gebruik in de culturele sector (bijv. json-ld of DERA) onderzocht op bruikbaarheid en schaalbaarheid; indien mogelijk worden deze ingezet.

Waarom niet één standaard en syntax? Omdat er een verscheidenheid aan instellingen bestaat die op een eigen decentrale manier onderdeel van de culturele sector moeten kunnen worden. Het belangrijkste is dat data machine readable wordt gemaakt zodat podia gegevens met elkaar kunnen uitwisselen om nieuw publiek te trekken en innovatieve vormen van samenwerken mogelijk te maken.

Er bestaan twee standaarden die op het internet veelvuldig gebruikt worden voor het uitwisselen en machine readable maken van agenda’s.

Schema.org/Event, van oorsprong met name geschikt voor zoekmachine optimalisatie (SEO). Deze standaard geniet de voorkeur vanwege het rijke schema, en developer-friendly syntax, belangrijk met het oog op nieuwe innovatieve toepassingen.
ICalendar-ics, van oorsprong met name geschikt voor hergebruik in agenda applicaties. Minder rijk maar laagdrempeliger, proven technology en defacto standaard van kalenderdata op het internet.

De kans bestaat dat je een van beide reeds gebruikt, dat is mooi! Kijk nog wel goed naar de checklist door om te zien of je de juiste velden deelt voor opencultuur.

Hoe publiceer ik een event voor hergebruik?

Stap 1. Checklist opencultuur agenda

Bepaald welke agenda-informatie je al digitaal tot je beschikking hebt, en welk gedeelte daarvan je wilt ontsluiten, en voor welk doel. Misschien moet er informatie worden toegevoegd die je nog mist. Bijvoorbeeld het handmatig toevoegen van steekwoorden aan je CMS, of het koppelen van prijsinformatie vanuit een ticketing systeem. Om hierbij te helpen vindt u hier een lijst van mogelijke velden die je machine readable gemaakt kunnen worden.

Metadata

Een uniek id. Dit kan de link naar de bronpagina zijn, als deze blijft bestaan, in ieder geval tot het event daadwerkelijk heeft plaatsgevonden. Omdat een event in meerdere lijsten voor kan komen is dit essentieel.
Sleutelwoorden die het mogelijk maken om het event te gericht te aggregeren en filteren, bijvoorbeeld op thema sterk aangeraden. Vraag je ook af welke keywords je gaat gebruiken, en hoe je deze afstemt met andere partijen. Zie Sectie 4
Een link naar de bron/eigenaar van het event sterk aangeraden.

Informatie over de inhoud van het evenement

Titel essentieel
Omschrijving sterk aangeraden
Plaatje(s). Traditionele agenda applicaties zoals Calendar tonen standaard geen plaatje. Als je deze wel beschikbaar hebt kun je door deze wel toe te voegen interesantte nieuwe toepassingen mogelijk optioneel
Artiest / informatie over wie er optreed optioneel

Informatie over wanneer het evenement live plaatsvindt

Starttijd essentieel
Eindtijd optioneel

Informatie waar het evenement live plaatsvindt (virtueel of fysiek)

Adres optioneel
Geolocatie optioneel
URL naar de live stream optioneel

Informatie over waar een stream van de registratie naderhand te bekijken is

URL van de registratie optioneel. Dit is de link naar de videoregistratie op een opencultuur PeerTube instantie, embedded op je eigen website of misschien een link naar YouTube of Vimeo?

Informatie over kaartverkoop / toegangsprijs

URL optioneel
Prijs optioneel

Optionele velden markeren we vooral zo omdat ze niet voor ieder agenda item relevant zijn, een online event heeft bijvoorbeeld geen fysiek adres en dus ook geen geolocatie. Maar als een van de genoemde velden wel relevant zijn voor een evenement, en je hebt de beschikking over de data, dan raden we altijd aan om het toe te voegen aan het machine readable event.

De bovenstaande set aan velden zijn gekozen met het elkaar helpen trekken van bezoekers in het achterhoofd. Maar beide standaarden bevatten in theorie nog veel meer mogelijke velden die je zou kunnen delen (bijvoorbeeld attendanceMode of eventStatus, of recurring events). En als je denkt dat het relevant is voor je eigen usecase kun je dat natuurlijk doen!

Stap 2. Hoe maak ik een evenement machine readable?

De tweede stap is het machine readable maken van de events zelf volgens een ICalendar of Schema.org representatie. Ook binnen ICalendar en Schema.org bestaan meerdere manieren om de data weer te geven. Kies er een die het best aansluit bij je wensen, dromen en uitgangs-situatie. De smaken hoeven elkaar niet uit te sluiten!

Smaak 1: Schema.org/Event - JSON-LD

Schema.org events in de json-ld syntax. Dit is de meest rijke representatie, en de keuze die in theorie het meest gemak kan opleveren voor externe ontwikkelaars. Deze optie heeft de voorkeur wanneer dat mogelijk is!

Je kunt hier voor kiezen als je als podium een ontwikkelaar hebt die dat kan implementeren, of als er bijvoorbeeld een plugin bestaat voor het CMS dat je gebruikt. Het is beter geschikt om pagination in te bouwen, als je meer events wilt delen dan er standaard op je web-agenda staan. Dit is een voorbeeld van een machine readable Event volgens schema.org:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "identifier": "afa9a885-1bcf-4184-937e-9e65b0e50b09",
  "name": "Museum Night x Waag: How to gain control over the algorithms?",
  "startDate": "2022-11-05T18:00:00+01:00",
  "endDate": "2022-11-06T01:00:00+01:00",
  "location": {
    "@type": "Place",
    "name": "Waag",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Nieuwmarkt 4",
      "addressLocality": "Amsterdam",
      "postalCode": "1012CR",
      "addressCountry": "NL"
    }
  },
  "description": "On Saturday 5 November, Waag opens their doors during Museum Night Amsterdam! Come on over and tame the algorithm, Do-it-Yourself DJ with AI, and have a chat with feminist chat bot #SOHPYGRAY.",
  "image": "https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms",
  "url": "https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms",
  "eventAttendanceMode": "https://schema.org/MixedEventAttendanceMode",
  "eventStatus": "https://schema.org/EventScheduled",
  "keywords": ["art & science", "algorithms"],
  "performer": {
    "@type": "Organization",
    "name": "Waag"
  }
}

We raden aan om JSON feed 1.1 te gebruiken om de events in je agenda als feed beschikbaar te maken. Dit is het meest vriendelijk voor hergebruik. Je kan daarnaast overwegen om de JSON-LD Events ook in je pagina’s op te nemen in een script tag, zodat je ook profijt hebt van SEO optimalisatie (zie hier).

Als dit is wat je zoekt, volg de uitgebreide documentatie van Google hier. Links naar libraries/plugins en nog veel meer over Schema.org kun je hier vinden op de Opencultuurdata Wiki

Smaak 2: Schema.org/Event - Microdata

Schema.org events als markup op de bestaande overzichts agenda pagina van je eigen website. Dit maakt de agenda pagina machine readable. Je kan de individuele event pagina’s ook annoteren als je die hebt. Dit heeft als bijkomend voordeel dat je website geoptimaliseerd wordt voor de Google zoekmachine. Een nadeel kan zijn dat je slechts de agenda items deelt die te zien zijn op je web pagina’s.

Het eerdere voorbeeld maar nu als geannoteerde microdata in HTML:

<div itemscope itemtype="https://schema.org/Event">
  <h1 itemprop="name">Museum Night x Waag: How to gain control over the algorithms?</h1>
  <p itemprop="description">On Saturday 5 November, Waag opens their doors during Museum Night Amsterdam! Come on over and tame the algorithm, Do-it-Yourself DJ with AI, and have a chat with feminist chat bot #SOHPYGRAY.</p>
  <p itemprop="startDate" content="2022-11-05T18:00:00+01:00">5 November 2022, 18:00 - 1:00</p>
  <p itemprop="endDate" content="2022-11-06T01:00:00+01:00">6 November 2022, 01:00</p>
  <p itemprop="location" itemscope itemtype="https://schema.org/Place">
    <span itemprop="name">Waag</span>
    <span itemprop="address" itemscope itemtype="https://schema.org/PostalAddress">
      <span itemprop="streetAddress">Nieuwmarkt 4</span>
      <span itemprop="addressLocality">Amsterdam</span>
      <span itemprop="postalCode">1012CR</span>
      <span itemprop="addressCountry">NL</span>
    </span>
  </p>
  <p itemprop="eventAttendanceMode" content="https://schema.org/MixedEventAttendanceMode">MixedEventAttendanceMode</p>
  <p itemprop="eventStatus" content="https://schema.org/EventScheduled">EventScheduled</p>
  <p itemprop="keywords">art & science, algorithms</p>
  <p itemprop="performer" itemscope itemtype="https://schema.org/Organization">
    <span itemprop="name">Waag</span>
  </p>
  <p itemprop="image" content="https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms"></p>
  <p itemprop="url" content="https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms"></p>
</div>

Voor meer informatie zie de eerder genoemde documentatie van Google of ga direct naar de schema.org specificatie. Links naar libraries/plugins en nog veel meer over microdata kun je hier vinden op de Opencultuurdata Wiki

Smaak 3: ICalendar - ICS

ICalendar events als een ICS bestand. Deze smaak is vooral handig als je bijvoorbeeld geen website hebt (omdat je alles via social media doet), en je events bijhoudt in een online calendar applicatie zoals iCloud of Google Calendar. Je kan ook ICS bestandjes met 1 event daarin publiceren op een Event pagina, handig voor bezoekers van je event die het ter herinnering in hun persoonlijke agenda willen opslaan.

BEGIN:VEVENT
UID:afa9a885-1bcf-4184-937e-9e65b0e50b09
SUMMARY:Museum Night x Waag: How to gain control over the algorithms?
DTSTAMP:20221008T140300Z
DTSTART:20221105T180000Z
DTEND:20221106T010000Z
DESCRIPTION:On Saturday 5 November\, Waag opens their doors during Museum N
    ight Amsterdam! Come on over and tame the algorithm\, Do-it-Yourself DJ wi
    th AI\, and have a chat with feminist chat bot #SOHPYGRAY.
URL:https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-alg
    orithms
LOCATION:Waag\nNieuwmarkt 4\n1012CR Amsterdam\n
CATEGORIES:art & science,algorithms
CREATED:20221003T113000Z
LAST-MODIFIED:20221008T122300Z
END:VEVENT

Voor meer informatie zie de documentatie op https://icalendar.org/ of de instructies op publicdata.events bijvoorbeeld als je geen website met cms hebt en ook nog geen agenda. Links naar libraries/plugins en nog veel meer over microformats kun je hier vinden op de Opencultuurdata Wiki

Smaak 4: ICalendar - Microformat

ICalendar events als markup op de bestaande agenda pagina’s van je eigen website. Net als de Schema.org/Microdata worden hiermee de agenda pagina’s op je website machine readable. Deze manier is het meest laagdrempelig omdat je alleen classes hoeft aan te passen. Je kan hier voor kiezen als je zonder ‘echt programmeren’ de events op je pagina’s toch machine readable wilt maken. Misschien heb je maar een paar events per jaar, en schrijf je alle aankondigen handmatig in HTML, dan is dit misschien een smaak die daar bij aansluit. Deze smaak maakt je event pagina’s ook beter indexeerbaar voor search engines, al is dit niet Google-eigen…

Het voorbeeld als microdata (v2):

<div class="h-event">
        <h2 class="p-name">Museum Night x Waag: How to gain control over the algorithms?</h2>
        <div class="dt-start" title="20221105T180000Z">5 November 2022</div>
        <div class="dt-end" title="20221106T010000Z">6 November 2022</div>
        <div class="p-description">On Saturday 5 November, Waag opens their doors during Museum Night Amsterdam! Come on over and tame the algorithm, Do-it-Yourself DJ with AI, and have a chat with feminist chat bot #SOHPYGRAY.</div>
        <div class="p-location">
        Waag
        Nieuwmarkt 4
        1012CR Amsterdam
        </div>
        <div class="p-url"><a href="https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms">https://waag.org/en/event/museum-night-x-waag-how-gain-control-over-algorithms</a></div>
        <div class="p-category">
                <span class="p-category">art &amp; science</span>
                <span class="p-category">algorithms</span>
        </div>
</div>

Voor meer informatie zie de documentatie Icalendar.org en op de microdata wiki. Links naar libraries/plugins en nog veel meer over microformats kun je hier vinden op de Opencultuurdata Wiki

Mapping van de opencultuur data velden

De standaarden bieden nog best wat ruimte voor interpretatie, zeker ICalendar/ICS, (stop ik de omschrijving in SUMMARY of DESCRIPTION? stop ik de link naar de videoregistratie in LOCATION of URL? etc.) daarom hier een overzicht van waar wij de informatie verwachten als je het op de opencultuur manier doet.

Mapping
Open cultuurdata	Schema.org/Event	ICalendar
Uniek ID	Identifier	UID
Sleutelwoorden	keywords	CATEGORIES
Bron	url*	URL
Titel	name	SUMMARY
Omschrijving	description	DESCRIPTION
Plaatje	image	IMAGE
Artiest	performer	-unsupported-
Starttijd	startDate	DTSTART
Eindtijd	endDate	DTEND
Adres	location.place	LOCATION
Geolocatie	location.place.geo	GEO
Livestream URL	location.virtuallocation	-unsupported-
Streamregistratie URL	location.virtuallocation	LOCATION
Kaartverkoop URL	offers	-unsupported-
Prijs	offers.price	-unsupported-

Zoals je kunt zien is ICalendar minder rijk qua schema. Er is geen manier om gestructureerd aan te geven wie er optreedt, wat de prijs van een event is, of waar tickets kunnen worden gekocht. Ook specificeert ICalendar maar één URL property en één LOCATION property per event. Als je kiest voor ICalendar betekent dat bijvoorbeeld dat het agenda item van een live opgenomen evenement vóór de livestream een (adres) locatie heeft in het LOCATION veld, maar dat de inhoud daarvan veranderd naar de URL van de registratie nadat het event heeft plaatsgevonden. Je kan de adres-gegevens bijvoorbeeld nog wel in de description opnemen, maar het adres is dan geen gestructureerde data meer.

Welke events publiceren?

Het gaat natuurlijk om de events die nog plaats gaan vinden, zodat er mogelijk meer bezoekers op af kunnen komen. Dit noemen we de agenda-feed. Het bevat alle events die je nu al op je website in je agenda publiceert (of zou publiceren). Bijvoorbeeld alles in het komende half jaar.

Historische events zullen vaak net even verschillen van de agenda-feed. Een eventuele livestream is niet meer beschikbaar, er kunnen geen kaartjes meer worden gekocht, en er is misschien een nieuwe link naar een videoregistratie.

Het kan zijn dat je video archief goed op orde is, bijvoorbeeld met peerTube en dat er daarmee automatisch een feed van historische events beschikbaar is. Maar misschien staan je video’s wel op verschillende platformen, en denk je dat een feed van historische events van waarde is voor hergebruik? Dan raden we aan om die ‘archief’ feed apart te publiceren.

Hoe publiceer ik een feed van events voor hergebruik op andere sites / apps?

Nadat je een of meer van de calendar standaarden hebt geimplementeerd wil je deze vindbaar maken voor andere partijen. Er zijn drie manieren om dat te doen. De reden hiervoor is wederom dat ieder podium anders is, sommige opties zijn technisch onmogelijk, bijvoorbeeld vanwege het gebruikte CMS of het feit dat een podium geen website heeft.

De drie smaken zijn, standaard url, meta tags en registratie op de wiki.

Standaard url

Gebruik een standaard url als je feeds gebruikt in de vorm: https://<podium.nl>/.opencultuur/agenda.<filetype> https://<podium.nl>/.opencultuur/archief.<filetype>

Waarbij je podium.nl vervangt door het domein van je eigen website, bijvoorbeeld

https://waag.org/.opencultuur/agenda.json voor een Schema.org/Event JSON agenda feed
https://waag.org/.opencultuur/agenda.ics voor een Icalendar / ICS agenda feed

of

https://waag.org/.opencultuur/archief.json voor een Schema.org/Event JSON archief feed
https://waag.org/.opencultuur/archief.ics voor een Icalendar / ICS archief feed

Meta tags

Het kan voorkomen dat je CMS die standaard url onmogelijk maakt, bijvoorbeeld omdat alle pagina’s worden geredirect naar een pad dat de locale (bv NL of EN) bevat. Of omdat je agenda pagina beschikbaar is op een ander platform dan je eigen website zoals op iCloud, Google (bah) of misschien wel publicdata.events of mobilizon?

Voeg dan de juiste meta tags om aan te geven waar je de feed kunt vinden op de home page van je webpagina, en onder welke standaard je ze beschikbaar hebt gemaakt. Voeg dan zeker een opencultuur-[feed]-[type] meta tag toe op in de <head> van je homepage. feed is hierbij archief of agenda en type is dan ics, json, microdata of microformat. Bijvoorbeeld:

Schema.org/JSON-LD:

<meta name="opencultuur-agenda-json" content="https://waag.org/nl/agenda.json"> Een link naar van de json-ld feed met agenda items.

<meta name="opencultuur-archief-json" content="https://waag.org/nl/agenda.json?past_events=yes"> Een link naar van de json-ld feed met historische agenda items.

Ical/ICS

<meta name="opencultuur-agenda-ics" content="https://<podium.nl>/EN/agenda.ics"> of bijvoorbeeld <meta name="opencultuur-agenda-ics" content="https://mobilizon/<podium.nl>/agenda.ics"> Een link naar de ics feed met agenda items.

Als je geen feeds gebruikt, maar alleen geannoteerde web pagina’s, dan kun je dit gebruiken.

Microdata event <meta name="opencultuur-agenda-microdata" content="https://<podium.nl>/EN/agenda.html"> Een link naar de Agenda webpagina op je website, geannoteerd met event microdata.
Microformat event <meta name="opencultuur-agenda-microformat" content="https://<podium.nl>/EN/agenda.html"> Een link naar de Agenda webpagina op je website, geannoteerd met het event microformat.

Opencultuur Wiki

Het kan natuurlijk ook voorkomen dat je helemaal geen website hebt (maar alleen op BeReal of TikTok zit), of dat je de meta tags niet aan kunt passen omdat je nog steeds op Facebook bent te vinden? Maak dan in iedere geval een aankondiging op de registratie pagina van de opencultuur wiki hier!

Maak altijd een aankondiging aan, ook als je een van de eerdere manier hebt gebruikt.

Afstemming met andere partijen

Dit is het absolute begin. We verwachten nog allerlei vragen na het lezen van de handleiding. Bijvoorbeeld:

Hoe vind ik andere partijen om mee samen te werken?
Hoe stemmen we meta data / keywords af?
Ik heb ook historische agenda data, zal ik die beschikbaar maken? Onder welke URL moet dat dan?
Ik wil mijn JSON feed alleen beschikbaar maken voor een bevriend podium, hoe beveilig ik dat?
Zijn er schema’s voor de keywords die ik kan gebruiken? Of bestaande ontologieeen?
Kan iemand me helpen met het implementeren van paging in JSON feeds?

We hopen dat het antwoord op al dit soort vragen in de toekomst worden opgelost in de community page op de OpenCultuur Wiki, dus deel al je oplossingen en ervaringen hier op deze Wiki!

↑ ^1,0 ^1,1 Projectplan Living Lab Open Cultuurdata

[pplloc-1] 1,0 ^1,1 Projectplan Living Lab Open Cultuurdata

[1]

Handleiding kalenderdata

Inhoud

Handleiding digitaal delen opencultuur agenda data

Inleiding

Digitaal delen van agenda data voor experiment en innovatie

Een decentrale aanpak voor behoud van autonomie

Bestaande open standaarden en onze voorkeur

Hoe publiceer ik een event voor hergebruik?

Stap 1. Checklist opencultuur agenda

Metadata

Informatie over de inhoud van het evenement

Informatie over wanneer het evenement live plaatsvindt

Informatie waar het evenement live plaatsvindt (virtueel of fysiek)

Informatie over waar een stream van de registratie naderhand te bekijken is

Informatie over kaartverkoop / toegangsprijs

Stap 2. Hoe maak ik een evenement machine readable?

Smaak 1: Schema.org/Event - JSON-LD

Smaak 2: Schema.org/Event - Microdata

Smaak 3: ICalendar - ICS

Smaak 4: ICalendar - Microformat

Mapping van de opencultuur data velden

Welke events publiceren?

Hoe publiceer ik een feed van events voor hergebruik op andere sites / apps?

Standaard url

Meta tags

Opencultuur Wiki

Afstemming met andere partijen

Navigatiemenu

Handleiding kalenderdata

Handleiding digitaal delen opencultuur agenda data

Inleiding

Digitaal delen van agenda data voor experiment en innovatie

Een decentrale aanpak voor behoud van autonomie

Bestaande open standaarden en onze voorkeur

Hoe publiceer ik een event voor hergebruik?

Stap 1. Checklist opencultuur agenda

Metadata

Informatie over de inhoud van het evenement

Informatie over wanneer het evenement live plaatsvindt

Informatie waar het evenement live plaatsvindt (virtueel of fysiek)

Informatie over waar een stream van de registratie naderhand te bekijken is

Informatie over kaartverkoop / toegangsprijs

Stap 2. Hoe maak ik een evenement machine readable?

Smaak 1: Schema.org/Event - JSON-LD

Smaak 2: Schema.org/Event - Microdata

Smaak 3: ICalendar - ICS

Smaak 4: ICalendar - Microformat

Mapping van de opencultuur data velden

Welke events publiceren?

Hoe publiceer ik een feed van events voor hergebruik op andere sites / apps?

Standaard url

Meta tags

Opencultuur Wiki

Afstemming met andere partijen

Navigatiemenu

Zoeken