Informatie Publicatie Model Samenwerkende Catalogi 4.0. Deel B: Technische Beschrijving. Versie 1.0. Datum 23 april 2012 Status Norm

Informatie Publicatie Model Samenwerkende Catalogi 4.0 Deel B: Technische Beschrijving Versie 1.0

Datum Status

23 april 2012 Norm

Informatie Publicatie Model Samenwerkende Catalogi 4.0 | 23 april 2012

Colofon

Projectnaam Versienummer Organisatie

Samenwerkende Catalogi 4.0 1.0 Logius Postbus 96810 2509 JE Den Haag [email protected]

Bijlage(n)

Documentbeheer

Datum

Versie Wijziging

Status

Verwerkt door

01-06-10

v0.9

Concept

MFA Aarts

28-07-10

v0.91 velden abstract en onlineaanvragen verplicht Concept gemaakt; omschrijving van de velden abstract, productHTML en eenmaligaanmelden aangepast; bij het waardebereik voor het veld language een verwijzing toegevoegd naar RFC 3066; URL van de XSD's voor SC4.0 veranderd in H3 (2x) en bijlage 1; onder bevoegd gezag GGD en Ministerie toegevoegd; onder locatie Koninkrijksdeel en GGD toegevoegd

MFA Aarts

20-08-10

v0.92 attendering webrichtlijnen toegevoegd aan 'Opbouw van het SC product'

GJ Mouwen

16-09-10

v0.95 gebruik nieuwe open-office template; gelijktrekken Concept met IPM deel A; diverse tekstuele aanpassingen; H2 informatie over producten & diensten in MijnOverheid verwijderd; website IPM's aangepast; aanpassing Universele Productenlijst → Uniforme

conceptversie, verspreid onder reviewgroep

Concept

MFA Aarts

Productnamenlijst; 2.3 toetsingscriteria aangepast; H3 voorbeelden en definities locatie / bevoegd gezag / uniforme productnaam / gerelateerd product aangepast; H3 aanbeveling productHTML toegevoegd en voorbeeld aangepast; H4 en H5 grotendeels herschreven en aangevuld 24-09-2010 v0.96 Minor opmaakaanpassingen, document info bijgewerkt Concept

G.J. Mouwen

04-11-10

MFA Aarts

v0.97 2.3.1 en H3: informatie over 'contactpunt' aangepast: Concept veld wel aanwezig, maar tot nader bericht niet vullen; H3: voorbeelden bij uniforme productnaam en gerelateerd product aangepast; H4 (UPL) informatie over mutaties, metadatering in het CMS, link naar de waardelijst en voorbeeld toegevoegd; 4.3 Themastructuren: diverse aanvullingen; 4.4 Contactinformatie: aangegeven dat dit niet in deze versie van het IPM is voorzien; 5.1.1 formulering

Pagina 2 van 36


HTTPs aangepast; 09-11-10

v0.971 Paragraaf 5.2 (SRU) grotendeels aangevuld en herschreven

Concept

MFA Aarts

12-11-10

V0.972 Kleine tekstuele aanpassingen; H6 gelijkgetrokken met IPM deel A; 4.3 URL en voorbeeld TiO/UPL aangepast; 5.2 rank veranderd van decimaal in percentage;

Concept

MFA Aarts

19-11-10

v0.973 Diverse tekstuele aanpassingen n.a.v. interne review

Concept

MFA Aarts

25-11-10

v0.974 Diverse tekstuele aanpassingen n.a.v. interne review

Concept

MFA Aarts

26-11-10

v0.975 H3.1 en H3.2 attribuut owms-version op scproduct ipv Concept scproducten H3.3.1 dcterms.authority veranderd in overheid.authority Voorbeeldberichten geactualiseerd H5.2.4 plaats van organisatie/postcode/organisatieType vooraan in de CQL query meer benadrukt H5.2.5 opmerking over foutbericht toegevoegd Voorbeeldberichten geactualiseerd

MFA Aarts

29-11-10

v0.976 Voorbeeld van een foutbericht toegevoegd en tekst aangepast in H5.2.5

Concept

MFA Aarts

19-12-11

V0.99 Hoofdstuknummering is aangepast H2.1 encoding is aangepast H3.1 uniforme productnamenlijst is aangepast H3.2 contentmodel product is aangepast H4.2 bevragen van de zoekdienst is herschreven

Specificatie RA van de Rijt

23-04-212 V1.0

Vermelding over IPM deel C aangepast.

Norm

RA van de Rijt

Referenties

Verwijzing Naam

Locatie

R1

http://www.logius.nl/samenwerkende-catalogi

IPM SC4.0 Deel B

Versie

Pagina 3 van 36


Samenvatting

Wat is Samenwerkende Catalogi? Samenwerkende Catalogi is een verwijsmechanisme voor productinformatie van overheidsorganisaties (lokaal, regionaal en landelijk). Deelnemende organisaties publiceren enerzijds metadata over hun producten conform de Samenwerkende Catalogi metadatastandaard. Anderzijds tonen zij de producten van andere organisaties op hun website. Dit mechanisme wordt gefaciliteerd door de zoekdienst voor Samenwerkende Catalogi. Behalve op de websites van deelnemende organisaties kan de informatie uit Samenwerkende Catalogi ook getoond worden op centrale portalen als www.overheid.nl en www.antwoordvoorbedrijven.nl. Samenwerkende Catalogi is dé eoverheidsbouwsteen als het gaat om informatie over producten en diensten. Wat biedt deel B van het Informatie Publicatie Model (IPM)? Dit technische deel van het IPM geeft uitleg over het uitwisselen van metadata over producten en diensten via het mechanisme van Samenwerkende Catalogi. Het document licht de XML schema's van Samenwerkende Catalogi en alle daarvoor relevante metadata toe en de manier waarop informatie kan worden uitgewisseld. Het doel van dit document is om leveranciers en overheden de informatie te verschaffen die nodig is om aan de technische eisen van het project Samenwerkende Catalogi te voldoen. Als aanvulling op dit technische IPM vindt u op http://standaarden.overheid.nl/sc/ het functionele gedeelte van dit IPM (Deel A: Functionele beschrijving) met een meer algemene beschrijving van de standaard voor Samenwerkende Catalogi. Hoe zien de XML schema's van Samenwerkende Catalogi er uit? De metadatastandaard voor Samenwerkende Catalogi schrijft voor dat de informatie over producten en diensten wordt gepubliceerd in XML formaat conform de SC XML schema's. Deze schema's zijn gebaseerd op de Overheid.nl Web Metadata Standaard (OWMS). Een XML bericht beschrijft meerdere producten. Per product wordt metadata opgenomen, bestaand uit drie groepen: de OWMS-kern, de OWMS-mantel, en additionele metadata specifiek voor Samenwerkende Catalogi. Dit IPM beschrijft de metadata van deze groepen. Naast deze metadata is het toegestaan per product een stuk opgemaakte XHTML bij te sluiten. Relatie met andere informatie Samenwerkende Catalogi is vooral een verwijsmechanisme. De productinformatie zelf is via Samenwerkende Catalogi vindbaar, en wordt gepresenteerd op de website van de betreffende organisatie. Productinformatie vormt de kern van menige e-overheidtoepassing, en daarom is het zaak dat Samenwerkende Catalogi aansluit bij andere modellen binnen de e-overheid. Door het gebruik van de Uniforme Productnamenlijst (UPL) kan de informatie uit Samenwerkende Catalogi gekoppeld worden aan bijvoorbeeld thema-indelingen of zaaktypen. Informatie over de betreffende organisatie zelf, zoals de regionale dekking Pagina 4 van 36


en contactpunten, valt formeel buiten de scope van Samenwerkende Catalogi, maar de standaard maakt het wel mogelijk om hiernaar te verwijzen.

Pagina 5 van 36


Inhoud

Colofon .......................................................................................... 2 Referenties .................................................................................... 3 Samenvatting ................................................................................ 4 Inhoud ........................................................................................... 6 Inleiding ........................................................................................ 8 1.1

Aanbieden van informatie ....................................................... 8

1.2

Afnemen van informatie ......................................................... 9

1.3 Voldoen aan de standaard voor Samenwerkende Catalogi ........... 9 1.3.1 Publiceren ..................................................................... 10 1.3.2 Zoekfunctie ................................................................... 10 1.3.3 Na de aansluiting ........................................................... 10 1.3.4 Wijzigingen ................................................................... 11 2

Het SC XML Schema................................................................ 12 2.1

Encoding ............................................................................ 12

2.2

Berichtstructuur................................................................... 13

2.3 Opbouw van het SCProduct ................................................... 13 2.3.1 OWMS-kern ................................................................... 14 2.3.2 OWMS-Mantel ................................................................ 16 2.3.3 SC meta........................................................................ 17 2.3.4 ProductHTML ................................................................. 20 3

4

Samenhang met andere informatie ........................................ 21 3.1

Uniforme Productnamenlijst (UPL) ......................................... 21

3.2

Contentmodel Product .......................................................... 22

3.3

Thema-indelingen ................................................................ 23

3.4

Contactinformatie ................................................................ 25

3.5

Geografische informatie ........................................................ 25

Het SC uitwisselmechanisme .................................................. 26 4.1 Aanbieden van informatie ..................................................... 26 4.1.1 Publicatie van het XML bestand ........................................ 26 4.1.2 Validatie ....................................................................... 26 4.2 Bevraging van de zoekdienst ................................................. 27 4.2.1 De opbouw van de URL ................................................... 27 4.2.2 Structuur van de CQL query ............................................ 29 4.2.3 Character escaping ......................................................... 30 4.2.4 Zoeken in velden............................................................ 30 4.2.5 Regionaal zoeken: uitbreiden van de zoekvraag met relevante organisaties .............................................................................. 31 4.2.6 Het zoekresultaat ........................................................... 33 Pagina 6 van 36


5

Meer informatie ...................................................................... 36

Pagina 7 van 36


Inleiding

Het Informatie Publicatie Model (IPM) Samenwerkende Catalogi 4.0 bestaat uit drie delen, te weten Deel A: Functionele beschrijving Deel B: Technische beschrijving Deel C: Zoekdienst Deel A (R1) is speciaal geschreven om de lezer te voorzien van meer informatie over de standaard, zonder dat hij over technische kennis hoeft te beschikken. Dit deel B beschrijft op welke manier overheidsorganisaties hun producten dienstinformatie dienen te publiceren om te voldoen aan de Standaard voor Samenwerkende Catalogi. Dit document is met name geschikt voor leveranciers en overheidsorganisaties die zelfstandig aansluiten op de standaard. Dit document, deel B, beschrijft Samenwerkende Catalogi vanuit een technisch oogpunt. Het is als volgt opgebouwd: Hoofdstuk Hoofdstuk Hoofdstuk Hoofdstuk Hoofdstuk

1: 2: 3: 4: 5:

De Standaard voor Samenwerkende Catalogi Het SC XML Schema Samenhang met andere informatie Het SC Uitwisselmechanisme Meer informatie

Deel C tenslotte, beschrijft de technische specificaties ten behoeve van de zoekdienst. De zoekdienst is een zoekmachine die in de aangeboden producten en diensten kan zoeken. De zoekdienst is te vergelijken met Google, alleen zoekt deze zoekdienst uitsluitend in aangeboden producten dienstinformatie die gepubliceerd is volgens de Standaard voor Samenwerkende Catalogi. Dit document (deel C) is niet beschikbaar voor geïnteresseerden. Het is bestemd voor intern gebruik en wordt met name gebruikt als specificatie voor de Zoekdienstleverancier. 1.1

Aanbieden van informatie De naam IPM zegt het al: in de eerste plaats is Samenwerkende Catalogi een model voor publicatie van informatie. Een overheidsorganisatie publiceert via Samenwerkende Catalogi metadata over haar producten en diensten, zodat deze bruikbaar is op andere plaatsen binnen de eoverheid. Om het voor afnemers eenvoudig te maken de metadata te verwerken, is de publicatiewijze gestandaardiseerd: de Standaard voor Samenwerkende Catalogi schrijft voor welke informatie gepubliceerd moet worden en in welke vorm. In lijn met de pas toe of leg uit-lijst van het Forum en College Standaardisatie is deze metadatastandaard gebaseerd op OWMS, de Overheid.nl Web Metadata Standaard. Deze schrijft een aantal metadatavelden voor die bij elke (overheids-)publicatie van toepassing zijn en biedt een raamwerk voor domeinspecifieke uitbreidingen (metadata speciaal voor productinformatie). Voor Samenwerkende Pagina 8 van 36


Catalogi betekent dit dat naast een aantal standaard OWMS velden (gebaseerd op de internationale standaard Dublin Core) ook een aantal SC-specifieke velden is toegestaan. De structuur van de metadata is vastgelegd in een XML Schema, dat in dit document wordt toegelicht. De productinformatie zelf blijft uitdrukkelijk 'bij de bron', d.w.z. op een productpagina op de website van de aanbiedende organisatie. De metadata bevat slechts een verwijzing naar deze productpagina's. Het XML Schema en de diverse metadatavelden vindt u in hoofdstuk 2. De wijze van publicatie wordt nader toegelicht in hoofdstuk 4. 1.2

Afnemen van informatie Behalve een metadatastandaard is Samenwerkende Catalogi ook een uitwisselmechanisme. Zo tonen op het moment van schrijven ruim 400 overheidsorganisaties informatie over de producten van andere organisaties op hun website door gebruik van Samenwerkende Catalogi. Om het afnemen van productinformatie te faciliteren biedt Logius de zoekdienst voor Samenwerkende Catalogi. Deze zoekdienst is een centrale voorziening waarin de informatie van alle deelnemende organisaties wordt verzameld en ontsloten. Door het aanspreken van de zoekdienst kunnen organisaties de productinformatie van andere organisaties eenvoudig opvragen en presenteren op hun eigen website of in hun eigen applicatie. De zoekdienst zorgt zelf voor actualisering van de gegevens, en bepaalt de 'routering', d.w.z. welke organisaties zijn relevant voor een zoekvraag. De zoekdienst bevat naast de collectie Samenwerkende Catalogi nog andere collecties zoals Bekendmakingen en Vergunningen, die op een soortgelijke wijze kunnen worden bevraagd. De website www.overheid.nl maakt gebruik van de zoekdienst en ontsluit daarmee een aantal collecties. Meer over de wijze van bevraging van de zoekdienst voor Samenwerkende Catalogi is te lezen in hoofdstuk 4. Sommige organisaties en portalen kiezen ervoor de informatie rechtstreeks bij de bron op te halen en te verwerken in hun systemen. Met deze partijen maakt Samenwerkende Catalogi afspraken over bijvoorbeeld actualiteit en belasting van de servers. Een voorbeeld van zo'n partij is Antwoord voor bedrijven, dat de gegevens ontsluit in het dienstenloket voor ondernemers uit heel Europa.

1.3

Voldoen aan de standaard voor Samenwerkende Catalogi Zoals in het bovenstaande beschreven werkt Samenwerkende Catalogi twee kanten op: deelnemers bieden enerzijds informatie aan, en gebruiken anderzijds de informatie van anderen uit de Samenwerkende Catalogi om deze te tonen op hun website. Een organisatie is dan ook 'aangesloten op Samenwerkende Catalogi' als deze: informatie over producten en diensten publiceert conform de specificaties zoals beschreven in dit document en het XML schema; op haar website een zoekfunctie biedt naar producten en diensten van andere overheden, zoals beschreven in dit document. Deze Pagina 9 van 36


eis geldt alleen voor gemeenten, provincies en waterschappen, niet voor 'andere organisaties' zoals GGD-en en uitvoeringsorganisaties. 1.3.1

Publiceren De aanlevering van producten en diensten wordt getoetst op de volgende punten: is het bestand toegankelijk via HTTP? Eventueel is HTTPs toegestaan, mits voorzien van een valide en geldig overheidscertificaat; voldoet het bericht aan het XML Schema? Hiervoor wordt de OWMS validator http://owmsvalidator.overheid.nl gebruikt; bevat de catalogus minimaal één werkelijk product? is het veld overheid:authority juist (conform verwachting) gevuld? is er een reële inspanning geleverd om daar waar dat relevant is te verwijzen naar Uniforme Productnamen? verwijzen de links in dcterms:identifier naar productpagina's in een live omgeving (d.w.z. geen testomgeving)?

1.3.2

Zoekfunctie Bij het testen van de zoekfunctie op de website van de organisatie worden de volgende punten getoetst: is de zoekfunctie bereikbaar vanaf de (live) website van de deelnemer? wordt de gebruiker in staat gesteld producten en diensten van alle relevante overheden te doorzoeken, zoals beschreven in hoofdstuk 4? Wanneer een deelnemer al deze toetsen doorstaat, voldoet hij aan de standaard. Daarnaast kan Samenwerkende Catalogi aanbevelingen doen om de aansluiting nog fraaier te maken. Wanneer een organisatie eenmaal „voldoet aan de standaard‟: zijn haar producten en diensten vindbaar via de loketten van andere deelnemers. Voor gemeenten geldt dat hun producten en diensten doorgaans niet via de loketten van andere gemeenten doorzocht worden; zijn haar producten en diensten vindbaar via de website www.overheid.nl; wordt een subset van haar producten en diensten ontsloten via de website www.antwoordvoorbedrijven.nl , mede ten behoeve van de Dienstenwet; is het voor andere (overheids-)organisaties mogelijk om hun diensten te koppelen aan aangeboden producten en diensten.

1.3.3

Na de aansluiting Dagelijks wordt door Samenwerkende Catalogi getoetst of de producten en diensten nog steeds (conform de standaard) worden aangeboden. Wanneer blijkt dat dit niet langer het geval is, wordt contact opgenomen met de contactpersoon van de deelnemer of de leverancier die de Pagina 10 van 36


koppeling tot stand heeft gebracht, om na te gaan wat het probleem is. Het functioneren van de zoekfunctie wordt periodiek met een steekproef gecontroleerd. Ook in dit geval zal bij problemen contact gezocht worden met de deelnemer of de leverancier. 1.3.4

Wijzigingen Mocht er een wijziging optreden in de technische configuratie (XML bestand op een andere URL, een nieuwe technische leverancier, een nieuwe website, etc.) dan verzoeken wij u om dit tijdig aan Samenwerkende Catalogi te melden zodat de nieuwe gegevens in de centrale collectie kunnen worden verwerkt. Bij voorkeur ontvangen wij uw bericht hierover uiterlijk één week voordat de URL wijziging plaatsvindt.

Pagina 11 van 36


2

Het SC XML Schema

Voor de publicatie van SC metadata wordt gebruik gemaakt van het Overheid.nl Web Metadata Standaard (OWMS) framework. Dit schrijft onder andere voor hoe de metadata gestructureerd dient te worden, in de vorm van een XML Schema. OWMS bestaat uit een aantal standaard metadata-elementen die worden toegekend aan overheidsinformatie. Hierdoor wordt de vindbaarheid en uitwisselbaarheid van de overheidsinformatie vergroot, bijvoorbeeld tussen de verschillende collecties die er gebruik van maken. OWMS maakt gebruik van een aantal waardelijsten, zoals een lijst met gemeentenamen. Deze lijsten kunnen in de loop van de tijd worden aangepast, bijvoorbeeld in het geval van herindelingen. De waardelijsten zijn te vinden op de website http://standaarden.overheid.nl. Informatie over producten en diensten wordt aangeleverd met een XML SC-bericht. Dit bericht bevat informatie over meerdere producten en diensten. De opbouw van het bericht is weergegeven in onderstaande afbeelding. Een SC-product is opgebouwd uit metadata en (indien gewenst) de XHTML van de productpagina (content). De metadata bestaat uit drie groepen: de OWMS-kern, de OWMS-mantel, en additionele metadata specifiek voor Samenwerkende Catalogi. De diverse onderdelen van het SC-bericht worden in dit hoofdstuk toegelicht. Meer informatie over het OWMS framework kunt u vinden op http://standaarden.overheid.nl. Het XML Schema zelf is te vinden op: http://standaarden.overheid.nl/sc/4.0/xsd/sc.xsd

2.1

Encoding Het XML bestand dient alleen tekens te bevatten uit de UTF-8 encoding. Daarnaast dient aan het begin van de indexfeed de volgende XMLdeclaratie te worden opgenomen:

Pagina 12 van 36


Indien deze XML-declaratie ontbreekt, zal de zoekdienst de indexfeed niet kunnen indexeren. Eventuele andere tekens dienen correct 'afgevangen' te worden door in de indexfeed gebruik te maken van ofwel een CDATA-blok of escape characters. Het gebruik van HTML-opmaak binnen de metadata (al dan niet afgevangen) is niet toegestaan; het is wel mogelijk om XHTML op te nemen in het element productHTML. 2.2

Berichtstructuur De volgende paragrafen beschrijven de verschillende velden, hun doel en mogelijke waarden. Zie voor een concrete implementatie van een SCbericht de voorbeeldberichten in de bijlage. Een SC-bericht maakt gebruik van de dcterms namespace van de Dublin Core, de generieke OWMS-overheidnamespace, een OWMS namespace specifiek voor productinformatie en de XSI namespace voor de koppeling met het bijbehorende XML Schema. De gebruikte namespaces kunnen in principe op verschillende manieren en met diverse prefixes worden gedeclareerd. U wordt verzocht de referentie naar de XML Schemalocation en de OWMS-versie (op elk 'scproduct') over te nemen. Element Status Komt voor Omschrijving

scproducten Verplicht Eén keer Containerelement voor de individuele 'scproduct' elementen, normaliter de plaats waar de namespaces gedeclareerd worden. Let op het gebruik van de spatie tussen de twee URLs in de declaratie van de schemaLocation.

XML ... ... ...

2.3

Opbouw van het SCProduct

Pagina 13 van 36


Het element scproduct is opgebouwd uit drie blokken, conform de Overheid.nl Web Metadata Standaard (OWMS), en een optioneel stuk XHTML. De metadata-blokken zijn: owmskern; owmsmantel; scmeta. In de OWMS kern is een minimale set van elementen opgenomen, met een aantal toegevoegde elementen in de owmsmantel. In scmeta zijn elementen opgenomen die specifiek voor Samenwerkende Catalogi zijn. Op het element scproduct dient het attribuut 'owms-version' met waarde “4.0” aanwezig te zijn. 2.3.1

OWMS-kern De OWMS kern is onderdeel van de OWMS. In de OWMS-kern is een set van acht eigenschappen opgenomen, namelijk: dcterms:identifier; dcterms:title; dcterms:language; dcterms:type; dcterms:modified; overheid:authority; dcterms:spatial; dcterms:temporal. Het laatste element is niet van toepassing voor Samenwerkende Catalogi en wordt daarom niet nader toegelicht. Door het invullen van deze eigenschappen is de metadata conform OWMS. Element

Identificatie

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Unieke verwijzing naar de productpagina op de website van de publicerende overheid. Deze verwijzing moet uniek zijn binnen de gehele SC-collectie. Zo wordt voor elk product bij elke organisatie een aparte productpagina verwacht, en is het niet toegestaan voor twee organisaties om naar dezelfde URI te verwijzen.

Waardebereik XML

xsd:anyURI http://www.vlist.nl/producten/Paspoort

Element

Titel

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

De titel is een vrij tekstveld en moet een korte omschrijving geven van het product zoals gehanteerd door de aanbiedende organisatie Pagina 14 van 36


Waardebereik Vrij tekstveld (zonder opmaak) XML

Burgerlijke Stand, aangifte geboorte van een kind

Element

Taal

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Taal van het document. Doorgaans is dat Nederlands (nl) , maar andere talen zijn in overleg mogelijk. Formeel moet een language code en country code (bv. nl-NL) worden meegegeven. Voor de eenvoud en uit oogpunt van backwards compatibility wordt echter 'nl' geadviseerd

Waardebereik xsd:language, zie http://www.ietf.org/rfc/rfc3066.txt XML

nl

Element

Informatietype

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Kenmerk waarmee aangegeven wordt dat dit bericht productinformatie bevat. Gelieve als 'scheme' overheid:Informatietype te specificeren.

Waardebereik Vaste tekst “productbeschrijving”. XML

productbeschrijving

Element

Datum laatste wijziging

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Aanvankelijk de datum waarop de informatie over het product is aangemaakt, en na een wijziging de datum van laatste wijziging. Gebruik bij voorkeur de notatie jjjj-mm-dd.

Waardebereik

xsd:date

XML

2008-08-31

Element

Bevoegd gezag

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Geeft het soort en de naam van de organisatie aan die verantwoordelijk is voor het publiceren van de productinformatie. Het 'scheme' geeft aan wat voor soort organisatie het betreft. De 'resourceIdentifier' is een unieke URI voor de organisatie. De tekstuele waarde van het veld is een label dat gebruikt kan worden voor presentatie van het zoekresultaat. Zowel de

Pagina 15 van 36


resourceIdentifier als het label dienen conform de OWMS te worden aangeboden Waardebereik Vaste waarde uit waardelijst (zie hieronder). Waardelijsten

overheid:Gemeente overheid:Waterschap overheid:Provincie overheid:Ministerie overheid:AndereOrganisatie overheid:GGD

XML

Vlist

Element

Locatie

Status

Verplicht.

Komt voor

Eén keer.

Omschrijving

Aanduiding van de regionale dekking van het product. Verwijs hier naar het betreffende concept in het OWMS framework. De vulling van het element is analoog aan overheid:authority. Indien het een landelijke dekking betreft vult u hier Koninkrijksdeel Nederland in. Indien uw organisatie(type) nog niet in het OWMS framework is opgenomen, neemt u contact op met de servicedesk. Zie voor meer informatie hoofdstuk 5.

Waardebereik Vaste waarde uit waardelijst (zie hieronder). Waardelijsten

overheid:Gemeente overheid:Waterschap overheid:Provincie overheid:Koninkrijksdeel overheid:GGD

XML

GGD Hart voor Brabant of: Nederland

2.3.2

OWMS-Mantel In de OWMS-mantel is een groot aantal extra elementen opgenomen, waarvan er binnen Samenwerkende Catalogi slechts drie worden gebruikt. Het zijn respectievelijk: dcterms:audience; dcterms:subject; dcterms:abstract. Pagina 16 van 36


Element

Doelgroep

Status

Verplicht.

Komt voor

Eén of twee keer.

Omschrijving

Aanduiding van de doelgroep waarvoor het product bedoeld is: particulier of ondernemer, of beide. In dat laatste geval wordt het element tweemaal opgenomen. Gelieve als 'scheme' overheid:Doelgroep te specificeren.

Waardebereik overheid:Doelgroep XML

ondernemer

Element

Onderwerp

Status

Optioneel

Komt voor

Nul of meer keer.

Omschrijving

Veld voor vrije tekst ten behoeve van de vindbaarheid van het product, zoals trefwoorden of thema-indelingen. Indien gewenst kan het veld vaker worden opgenomen, bijvoorbeeld eenmaal voor lopende tekst en eenmaal voor trefwoorden.


immigratie, machtiging tot voorlopig verblijf, verblijfsvergunning

Element

Samenvatting

Status

Verplicht.

Komt voor Omschrijving

Eén keer. Korte beschrijving van het product, ter presentatie in de zoekresultatenlijst van afnemers. Een lengte van ongeveer 300 tekens wordt aangeraden. Let erop dat de tekst leesbaar moet zijn voor een doorsnee eindgebruiker (burger of ondernemer) en bruikbaar voor het bepalen van de relevantie van dit product in een lijst zoekresultaten


Er is sprake van ontgronding als het maaiveld wordt verlaagd. De bodem wordt dan door afgraving ontdaan van een grondstoflaag zoals klei, veen, zand of grind.

2.3.3

SC meta De elementen binnen scmeta voegen nadere informatie toe over het product die niet binnen OWMS valt. Deze elementen vallen binnen de product-specifieke namespace overheidproduct ( http://standaarden.overheid.nl/product/terms/ ) Element

Product ID

Status

Verplicht.

Komt voor

Eén keer.

Pagina 17 van 36


Omschrijving

Unieke aanduiding van het product binnen de catalogus van de organisatie.


1234

Element

Online aanvragen

Status

Verplicht

Komt voor

Eén keer.

Omschrijving

Geeft aan of het product online is aan te vragen, en zo ja of hiervoor DigiD wordt gebruikt. Indien niet van toepassing, vult u hier 'nee' in.

Waardebereik Vaste waarde uit waardelijst: 'ja', 'nee' of 'digid' XML

a

Element

Aanvraag URL

Status

Optioneel.

Komt voor

Nul of één keer.

Omschrijving

Geeft aan waar het product online is aan te vragen, bijvoorbeeld een elektronisch formulier. De URL wordt in het attribuut 'resourceIdentifier' gespecificeerd.

Waardebereik xsd:anyURI XML

Element

Eenmalig aanmelden

Status

Optioneel.

Komt voor

Nul of één keer.

Omschrijving

Geeft aan of het aanvragen van het product door eenmalig aan te melden vanuit MijnOverheid mogelijk is, d.w.z. of de 'aanvraagURL' vanuit MijnOverheid bereikbaar is zonder extra in te loggen.

Waardebereik Vaste waarde uit waardelijst: ja of nee XML

ja

Pagina 18 van 36


Element

Contactpunt

Status

Optioneel.

Komt voor

Nul of één keer.

Omschrijving

Met dit veld wordt verwezen naar een contactpunt. Vooralsnog wordt aangeraden dit veld niet te vullen, maar wel te reserveren voor toekomstig gebruik.


Element

Uniforme productnaam

Status

Optioneel.

Komt voor

Nul of meer keer.

Omschrijving

Geeft aan welk product uit de Uniforme Productnamenlijst (UPL) het betreft, in de vorm van een verwijzing. Als het een product betreft dat niet in de UPL voorkomt, kies dan de waarde “UPL-naam nog niet beschikbaar”. Als het product overeenkomt met meerdere producten uit de UPL, kan het element meerdere malen worden herhaald. Voor meer informatie, zie hoofdstuk 5. Gelieve als'scheme' overheid:UniformeProductnaam te specificeren. De pointer wordt in het attribuut resourceIdentifier gespecificeerd. De waarde van het element komt uit de OWMS waardelijst.


afvaldoorzoekingsvergunni ng

Element

Gerelateerd product

Status

Optioneel.

Komt voor

Nul of meer keer.

Omschrijving

Als het product niet in de Uniforme Productnamenlijst (UPL) voorkomt, kan dit veld gebruikt worden om aan te geven aan welk product uit de UPL het gerelateerd is. Indien gewenst kunnen meerdere gerelateerde producten gespecificeerd worden door het veld te herhalen. Voor meer informatie, zie hoofdstuk 5. Gelieve als 'scheme' overheid:UniformeProductnaam te specificeren. De pointer wordt in het attribuut resourceIdentifier gespecificeerd. De waarde van het element komt uit de OWMS waardelijst.


Pagina 19 van 36


Afvaldoorzoekingsvergunning

2.3.4

ProductHTML Naast de metadata kan ook een stuk XHTML worden gespecificeerd, dat kan worden gepresenteerd door afnemers van de SC-content op hun websites. 'Hogere' overheden, d.z.w. alle organisaties behalve gemeenten, wordt sterk aangeraden dit veld te vullen, omdat veel gemeenten er voor kiezen om een beschrijvende tekst over uw product op de gemeentelijke website te tonen, alvorens de gebruiker door te laten klikken naar uw website. Element Status Komt voor Omschrijving

Product HTML Optioneel. Nul of één keer. Bevat een fragment opgemaakte XHTML. Houd er bij de vulling van dit veld rekening mee dat de XHTML valide is en gepresenteerd moet kunnen worden als onderdeel van een willekeurige (overheids-)website. XHTML elementen kunnen direct worden opgenomen, d.w.z. zonder escaping. Let erop dat de tekst in dit veld leesbaar is voor de eindgebruiker (burger of ondernemer) en deze uit moet nodigen om 'door te klikken' naar de productpagina bij de organisatie die het product aanbiedt. Gelieve de namespace en schemaLocation over te nemen. Denk bij de vulling van dit veld ook aan de webrichtlijnen: het moet getoond kunnen worden op de website van een overheidsorganisatie. Waardebereik XHTML Voorbeeld XML:
Aangifte doen van de geboorte van uw kind is verplicht.

De vader moet de aangifte van de geboorte van zijn kind doen.

Als de vader geen aangifte kan doen, moet iemand aangifte doen die aanwezig was bij de geboorte.

De moeder mag aangifte doen maar is dit niet verplicht

Pagina 20 van 36


3

Samenhang met andere informatie

3.1

Uniforme Productnamenlijst (UPL) De standaard voor Samenwerkende Catalogi maakt gebruik van de Uniforme Productnamenlijst (UPL). Deze lijst maakt het mogelijk om de informatie uit Samenwerkende Catalogi te koppelen aan andere informatie binnen de e-overheid zonder daarbij rekening te hoeven houden met de verschillende implementaties van productcatalogi bij overheidsorganisaties. Deze worden door de UPL ontkoppeld: aanbieders koppelen hun lokale catalogus aan de UPL, en afnemers koppelen hun applicatie aan de UPL. Om vervolgens tóch lokale informatie te kunnen tonen, wordt de zoekdienst voor Samenwerkende Catalogi aangesproken, die op verzoek de lokale variant van het betreffende product levert. Op deze manier kan de (veelal lokale) SC-informatie gekoppeld worden aan andere soorten informatie, zoals Vraag-antwoordcombinaties, ondernemersproducten op de website www.antwoordvoorbedrijven.nl, of een cluster machtigbare producten van DigiD Machtigen. Een voorbeeld: een gemeente biedt een product 'evenement organiseren' aan. Dit wordt in de SC aanlevering voorzien van de Uniforme Productnaam 'evenementvergunning'. Centrale loketten zoals het dienstenloket van Antwoord voor bedrijven kunnen nu eenvoudig verwijzen naar de productpagina bij de gemeente door te zoeken naar producten die met 'evenementvergunning' zijn aangeduid, ook al worden deze lokaal onder een andere naam aangeboden. Indien een organisatie een 'uniform product' in haar catalogus als meerdere producten benoemt (bijvoorbeeld 'buurtfeest' en 'braderie' i.p.v. één evenementvergunning), kunnen beide lokale producten in de SC aanlevering voorzien worden van dezelfde Uniforme Productnaam. Indien een organisatie een 'uniform product' in haar catalogus aanbiedt als onderdeel van een groter product (bijvoorbeeld 'WMO voorziening' i.p.v. aparte producten voor rolstoel en scootmobiel), dan kunnen aan dat lokale product meerdere Uniforme Productnamen worden toegekend. Indien een organisatie een product in haar catalogus aanbiedt dat niet in de UPL voorkomt, dient u in het veld 'uniformeProductnaam' de waarde UPL-naam nog niet beschikbaar op te nemen. Tevens kunt u aangeven dat het product iets te maken heeft met een of meerdere producten uit de UPL, door daarnaar te verwijzen in het veld 'gerelateerdProduct'. Bijvoorbeeld: een gemeente heeft een speciale gemeente-specifieke subsidie voor het organiseren van een buurtfeest. Dat is niet hetzelfde als een evenementvergunning, maar heeft daar wel mee te maken. In het veld 'gerelateerdProduct' wordt dan verwezen naar het UPL product evenementvergunning. Een organisatie die de evenementvergunning op haar website toont, kan daarbij dan eventueel ook deze gerelateerde producten tonen. De Uniforme Productnamenlijst is opgesteld door het team Contentregie van e-Overheid voor Burgers in samenspraak met o.a. Antwoord voor bedrijven, Regelhulp en KING. Op het moment van schrijven bevat de lijst zo'n 600 productnamen. Pagina 21 van 36


Er zijn verschillende manieren om metadatering van producten in een CMS mogelijk te maken. Hierbij kan gedacht worden aan een 'platte lijst' met alle uniforme productnamen, maar bijvoorbeeld ook aan een zoekfunctie of een thematische indeling (zie 4.3). Daarnaast heeft het team Contentregie een overzicht opgesteld waarin voor elke uniforme productnaam varianten worden opgesomd, dat eventueel ook kan worden gebruikt om de juiste productnaam bij een lokaal product te zoeken. De Uniforme Productnamenlijst is gepubliceerd als waardelijst in het OWMS framework: http://standaarden.overheid.nl/owms/terms/UniformeProductnaam.xml . Dit is een 'levende' lijst of 'afspeellijst', d.w.z. dat in deze lijst mutaties kunnen plaatsvinden: vervallen producten kunnen na verloop van tijd uit de lijst verwijderd worden, en nieuwe kunnen worden toegevoegd. Technisch gezien kan dat tot gevolg hebben dat u in uw aanlevering verwijst naar producten die niet meer in de lijst voorkomen, waardoor de aanlevering niet meer voldoet. Wij verzoeken u bij het bouwen van de applicatie hier rekening mee te houden. Om deelnemers ruim de tijd te geven hun verwijzingen aan te passen worden vervallen producten pas bij de volgende release definitief uit de lijst verwijderd. De waardelijst bestaat uit een 'root element' 'cv' (controlled vocabulary) met daarin 'value' elementen voor elke uniforme productnaam. Bij elke waarde is een 'prefLabel' en een 'resourceIdentifier' opgenomen, die beide in de Samenwerkende Catalogi metadata opgenomen dienen te worden om een verwijzing naar de productnaam aan te brengen. Een voorbeeld van een waarde uit de UPL: <prefLabel>afvaldoorzoekingsvergunning http://standaarden.overheid.nl/owms/terms/afvaldoorzoekingsvergunning

In de Samenwerkende Catalogi metadata kan als volgt naar dit product worden verwezen (bijvoorbeeld vanuit een lokaal product 'Afval doorzoeken, vergunning'): afvaldoorzoekingsvergunning 3.2

Contentmodel Product Het IPM Samenwerkende Catalogi 4.0 is nadrukkelijk een model voor uitwisseling van metadata over producten ten behoeve van vindbaarheid. De inhoudelijke productinformatie wordt daarbij niet uitgewisseld. EOverheid voor Burgers heeft daarnaast een model ontwikkelt waarmee Pagina 22 van 36


deze informatie wél kan worden uitgewisseld: het Contentmodel Product. Met dit model kan bijvoorbeeld een uitvoeringsorganisatie productinformatie leveren voor gebruik in een gemeentelijk klantcontactcentrum. Voor het uitwisselen van productinformatie (SC of het uitgebreidere Contentmodel Product) wordt één OWMS-model gebruikt. De velden uit het SC bericht komen ook voor in het Contentmodel Product. Hierdoor kunt u eenvoudig informatie leveren aan de SC zoekdienst, verwerken in uw eigen website en gebruiken voor uw Klant Contact Centrum (KCC). 3.3

Thema-indelingen Naast de zoekingang op basis van trefwoord zijn er veel afnemers die de producten uit Samenwerkende Catalogi willen ontsluiten via een themaindeling. De Standaard voor Samenwerkende Catalogi maakt dat mogelijk. Afnemers kunnen hun thema-indeling koppelen aan de Samenwerkende Catalogi zonder dat zij daarbij geconfronteerd worden met verschillende soorten catalogi, naamgeving van producten of wijzigingen in lokale catalogi. De Uniforme Productnamenlijst maakt dit mogelijk. Uw thema's kunnen gekoppeld worden aan de generieke producten die in deze lijst staan. De zoekdienst voor Samenwerkende Catalogi levert vervolgens de producten van de gewenste organisaties die met de betreffende Uniforme Productnaam zijn aangeduid. Zo kan bijvoorbeeld een thema 'Reizen' in een willekeurige thema-indeling gekoppeld worden aan de Uniforme Productnaam 'paspoort', onafhankelijk van de organisaties die dit product bieden. Om toch een lokale vindplaats van dit product te kunnen presenteren, kan de zoekdienst worden aangesproken met de vraag 'geef mij de producten van gemeente Breda die aangeduid zijn met de Uniforme Productnaam 'paspoort'. Dat kan bijvoorbeeld leiden tot producten als 'Aanvragen Paspoort' of 'Paspoort verloren' van gemeente Breda. Naast het opvragen van producten die met een Uniforme Productnaam zijn aangeduid, kunnen ook producten worden opgevraagd die zijn gerelateerd aan Uniforme Productnamen. Deze kunnen eventueel als extra informatie worden gepresenteerd. Om Samenwerkende Catalogi eenvoudig via een thema-indeling toegankelijk te maken is er een Thema-indeling Overheid (TiO) beschikbaar, inclusief de Uniforme Productnamen per thema. Met deze thema-indeling en de zoekdienst kunt u een thematische ingang implementeren voor zowel lokale als landelijke informatie uit de SCcollectie. Merk op dat de Thema-indeling Overheid uitsluitend gericht is op producten die relevant zijn voor burgers. De TiO is beschikbaar als onderdeel van het OWMS framework en te downloaden via: http://standaarden.overheid.nl/owms/4.0/doc/waardelijsten/overheid.the maindelingoverheid_v1.6.html . De koppeling TiO/UPL wordt gepubliceerd op: http://standaarden.overheid.nl/sc/4.0/relatie_UPL-TIO.xml . Hierin staan de thema's en bijbehorende producten in de vorm van XML (SPARQL) zodat u ze op uw eigen manier kunt verwerken in uw applicatie. Pagina 23 van 36


Merk op dat zowel de TiO als de UPL 'levende' lijsten zijn en dus aan verandering onderhevig, zie hiervoor ook paragraaf 3.1. In het XML bestand komt voor elke koppeling thema/productnaam een 'result' voor met daarin de volgende informatie: Thema (uri); Thema_label (tekst); soort relatie (SKOS 'related match'); UniformeProductnaam (uri); UniformeProductnaam_label (tekst). De URI's komen overeen met de resourceIdentifiers uit de waardelijsten (TiO en UPL); de labels komen overeen met de prefLabels uit de waardelijsten. Een voorbeeld van een thema met bijbehorend UPL product: http://standaarden.overheid.nl/owms/terms/gehandicaptenparkeerkaart gehandicaptenparkeerkaart http://standaarden.overheid.nl/product/terms/relatedMatch http://standaarden.overheid.nl/owms/terms/Parkeren_(thema) Parkeren

Indien u geen gebruik maakt van de TiO maar een eigen thema-indeling, dan kunt u uw thema's op een soortgelijke manier koppelen aan de Uniforme Productnamen. Meer informatie over de Thema-indeling Overheid is te vinden op: http://standaarden.overheid.nl/owms/4.0/doc/waardelijsten/overheid.the maindelingoverheid_v1.6.html

Pagina 24 van 36


3.4

Contactinformatie De relatie tussen producten contactinformatie wordt in deze versie van het IPM 4.0 nog niet gespecificeerd. Het metadataveld 'overheidproduct:contactpunt' is wel aanwezig en gereserveerd voor toekomstig gebruik.

3.5

Geografische informatie Veel organisaties hebben slechts een beperkte regionale dekking. De geografische informatie over organisaties valt feitelijk buiten de scope van Samenwerkende Catalogi en wordt dus niet direct expliciet in de SC XML vermeld: deze bevat slechts een verwijzing. U geeft in de SC aanlevering aan welke organisatie het betreft, en de SC zoekdienst bepaalt welke regionale dekking daar bij hoort. Hiervoor beschikt de zoekdienst over twee bronnen: de (commerciële) postcodetabel met relaties tussen gemeenten, (4-cijfer) postcodes en provincies; het OWMS framework met daarin geografische relaties tussen diverse soorten organisaties. Momenteel zijn dat de relaties gemeente-waterschap, gemeente-provincie en gemeente-GGD. De regionale dekking van regionale 'andere organisaties' dient door de organisaties zelf te worden gespecificeerd voordat ze in de SC-collectie kunnen worden opgenomen. Vervolgens zorgt het OWMS team ervoor dat deze informatie beschikbaar komt in het OWMS framework. Vanuit de SC XML kan dan naar het betreffende OWMS concept worden verwezen. Voor producten die landelijk geleverd worden kan aangegeven worden dat zij gelden voor Koninkrijksdeel 'Nederland'. Het doorzoeken van de SC-collectie kan vanaf een postcode of vanuit een gemeente. De SC zoekdienst bepaalt vervolgens welke organisaties daar relevant zijn, bijvoorbeeld welke GGD of provincie actief is in een postcodegebied. Meer hierover leest u in hoofdstuk 5. Indien u geen gebruik maakt van de SC zoekdienst, maar de SC informatie wel wilt presenteren, dient u ook de regionale verbanden zelf te implementeren. De informatie in het OWMS framework is daarbij vrij te gebruiken, en in de vorm van een XML beschikbaar op standaarden.overheid.nl . De postcode-informatie kunt u indien gewenst zelf afnemen van postcode.nl of een andere bron.

Pagina 25 van 36


4

Het SC uitwisselmechanisme

Behalve een standaard voor metadata over producten is Samenwerkende Catalogi ook een uitwisselmechanisme. Enerzijds kunt u informatie aanbieden conform dit mechanisme, en anderzijds kunt u informatie afnemen. Beide aspecten worden in dit hoofdstuk toegelicht. 4.1

Aanbieden van informatie

4.1.1

Publicatie van het XML bestand Om opgenomen te worden in de SC-collectie dient een organisatie haar productinformatie te publiceren op internet in de vorm van een XML bestand. De opbouw van dit bestand is beschreven in hoofdstuk 3. Bij deze publicatie hiervan geldt een aantal eisen: de URL is vrij toegankelijk via HTTP, d.w.z. zonder username/wachtwoord of uitsluiting van bepaalde IP-adressen; HTTPs is toegestaan, mits een geldig PKIoverheid certificaat meegeleverd wordt. Voor meer informatie over PKIoverheid certificaten, zie: http://www.logius.nl/producten/toegang/pkioverheid/; het juiste content-type (text/xml of application/xml) wordt meegegeven in de response headers; Het is belangrijk dat de webserver „robots‟ toestemming geeft deze bestanden op te halen. De zoekdienst harvester stuurt geen http headers mee. Dus er dient geen verplichting te zijn voor http headers. De URL van het XML-bestand dient aangemeld te worden bij de servicedesk van Samenwerkende Catalogi. Ook wanneer de URL van een XML-bestand wijzigt (bijvoorbeeld bij een nieuwe website) kunt u terecht bij de servicedesk. Om de wijziging tijdig te kunnen verwerken wordt u verzocht deze minimaal een week van tevoren door te geven aan de servicedesk . Het is een organisatie toegestaan meerdere XML bestanden aan te leveren, bijvoorbeeld een voor de ondernemersproducten en een voor de burgerproducten. Om e.e.a. beheersbaar te houden verzoeken we u om dit tot twee bestanden per organisatie te beperken.

4.1.2

Validatie Valideer uw XML-bestand voordat u het aanbiedt met de online OWMSvalidator op http://owmsvalidator.overheid.nl. Deze voorziening vertelt u of het bestand aan het OWMS-framework en meer specifiek het SC XMLSchema voldoet, en zo nee wat er niet juist is. Succesvolle validatie is een indicatie voor de ontvangende partij dat het bericht juist is opgesteld en daarom ook zonder problemen te verwerken is. Bij eerste aansluiting wordt deze toets ook door Samenwerkende Catalogi uitgevoerd als onderdeel van het aansluitproces. Vervolgens wordt frequent getoetst of de aanleveringen nog valide zijn. Als dit niet het geval is, kan niet gegarandeerd worden dat de informatie kan worden verwerkt door de afnemers, waaronder de SC Zoekdienst. De zoekdienst zal deze producten Pagina 26 van 36


niet indexeren zolang de aanlevering fouten bevat. Het gevolg is dat de producten niet langer vindbaar zijn via de websites van afnemers. Zorg er daarom voor dat het XML-bestand altijd voldoet aan het XML Schema en de bovenstaande eisen m.b.t. publicatie. Het gepubliceerde bestand wordt opgehaald door de zoekdienst van Samenwerkende Catalogi en eventuele andere afnemers (overheid en commercieel) met wie Samenwerkende Catalogi een overeenkomst heeft gesloten. De zoekdienst haalt het bestand eenmaal per dag op en ververst vervolgens de informatie in de collectie. Als het bestand niet toegankelijk is of niet correct, wordt het niet verwerkt en zullen de betreffende producten niet meer vindbaar zijn. Hierbij geldt dat de organisatie zelf verantwoordelijk is voor een correcte aanlevering. Doorgaans geldt dat mutaties in de bestanden een dag later in de zoekdienst zijn verwerkt. Met de overige afnemers zijn afspraken gemaakt over het ophalen van de bestanden, actueel houden van de informatie en de belasting die dat met zich mee brengt voor de servers van de dienstaanbieders. 4.2

Bevraging van de zoekdienst Voor het bevragen van de zoekdienst wordt gebruik gemaakt van de standaard SRU: Search /Retrieval via URL: een gestandaardiseerd zoekprotocol voor het zoeken op internet. Deze zoekingang wordt ook geboden voor andere collecties op www.overheid.nl. Formeel kent SRU ook een webservice-variant, waarbij de zoekvraag via het posten van een SOAP-bericht wordt ingeschoten. De aanbevolen manier van bevraging is echter via URL en deze variant wordt in dit document dan ook beschreven. Zoekvragen worden aangeboden in de vorm van een URL met parameters. De zoekdienst antwoordt vervolgens met een XML bestand, waarin de zoekresultaten zijn opgenomen. Deze resultaten bevatten tevens de originele 'scproducten' zoals die aan de zoekdienst zijn aangeleverd. Hierbij wordt een uitzondering gemaakt voor het dcterms:subject veld, dat vanuit commercieel oogpunt niet wordt verstrekt. Meer informatie over de SRU standaard en de gebruikte query-taal CQL is te vinden op: http://www.loc.gov/standards/sru/

4.2.1

De opbouw van de URL De bevragings-URL is opgebouwd uit een vast deel en een variabel deel. Het vaste deel luidt als volgt: http://zoekdienst.overheid.nl/SRUServices/SRUServices.asmx/Search?ver sion=1.2&operation=searchRetrieve&xconnection=sc&recordSchema=sc4.0&startRecord=1&maximumRecords= 10&query= De parameters version, operation, x-connection en recordSchema dient u mee te geven om te zorgen dat u de juiste collectie doorzoekt en vraag en antwoord conform deze specificaties zijn vormgegeven. De URL parameters startRecord en maximumRecords zijn optioneel. Deze worden doorgaans in combinatie gebruikt om een beperkte set resultaten op te vragen, bijvoorbeeld resultaat 11-20 van de in totaal 600 Pagina 27 van 36


zoekresultaten. Met startRecord wordt aangegeven vanaf welk record resultaten moeten worden teruggegeven (in geval van het voorbeeld: 1) en met maximumRecords hoeveel er totaal moeten terugkomen (in het voorbeeld: 10). Het variabele deel volgt achter de 'query' parameter en bevat de daadwerkelijke zoekvraag in de vorm van een 'CQL query'. De zoekcriteria kunnen het best worden gegroepeerd met behulp van haakjes: ( en ). In ieder geval dienen zowel de locatieaanduiding als de zoekcriteria van elkaar te worden gescheiden door middel van haakjes. Een zoekquery is opgebouwd uit twee onderdelen: een locatieaanduiding (postcode/organisatie, organisatietype); en zoekcriteria (audience, keyword, etc.). Wanneer beide onderdelen worden gebruikt gelden de volgende regels: A. De locatieaanduiding en (overige) zoekcriteria moeten worden gescheiden door haken; B. De locatieaanduiding moet altijd aan het begin van de query worden opgenomen. Voorbeeld 1: query= ((organisatie="Haarlemmermeer") and (organisatietype="Provincie" or organisatietype="GGD" or organisatietype="Waterschap" or organisatietype="Ministerie" or organisatietype="AndereOrganisatie")) and (keyword="water") Met deze standaard query bevraag je producten en diensten van alle organisaties met keyword water behalve de producten en diensten van de eigen gemeente, in dit geval Haarlemmermeer. Het organisatietype=Gemeente is namelijk niet meegenomen in de query. Voorbeeld 2: query= ((postcode="6290") and (organisatietype="Ministerie" or organisatietype="AndereOrganisatie")) and ((keyword="water") and (audience="ondernemer")) Voorbeeld 3: query=((organisatie="Nieuwegein") and ((keyword ="vitaliteitssparen") and (modified >= "2010-09-19") and (modified <= "2011-09-29"))) De volgende query is foutief, omdat niet is voldaan aan de voorwaarde onder A: query=((organisatie="Nieuwegein") and (keyword ="vitaliteitssparen") and (modified >= "2010-09-19") and (modified <= "2011-09-19")) De volgende query is foutief, omdat niet is voldaan aan de voorwaarden onder B: query=(((keyword ="vitaliteitssparen") and (modified >= "2010-09-19") and (modified <= "2011-09-19")) and (organisatie="Nieuwegein"))

Pagina 28 van 36


Beide foutieve queries leiden wel tot resultaten maar dit zijn niet de gewenste resultaten. 4.2.2

Structuur van de CQL query Een CQL query bevat de zoekcriteria die worden uitgedrukt met behulp van velden en operatoren. De volgende SRU-operatoren zijn toegestaan in de zoekvraag: Relaties =

== < > <= >= == adj all any

volledige match, tekst komt voor in het betreffende veld. De zoekdienst interpreteert dit feitelijk als een == voor numerieke data of een adj voor een string vergelijking, van toepassing op het datum-veld 'modified'

volledige match, numerieke informatie komt exact overeen met de waarde in het betreffende veld resultaten bevatten de opgegeven zoektermen in exact de volgorde als opgegeven : een zogenaamde “exact phrase search” resultaten bevatten de opgegeven zoektermen in willekeurige volgorde resultaten bevatten in ieder geval een van de opgegeven zoektermen

Booleans and resultaten moeten aan beide criteria wordt voldaan or r resultaten moeten aan minstens één van beide criteria voldoen not resultaten moeten niét aan het criterium achter 'not' voldoen Wildcards * wildcard ? wildcard voor 1 willekeurig karakter in een string Met bovengenoemde operatoren kunnen de zoekcriteria worden samengesteld tot één query. Let op: zoektermen dienen in de query tussen dubbele aanhalingstekens ("") te worden opgenomen. Het gebruik van dubbele aanhalingstekens betekent in SRU geen exact phrase search zoals dat voor andere zoekmachines vaak wel geldt. Hiervoor wordt bij SRU de 'adj' (adjacent) relatie gebruikt. Let op: Wildcards en relaties anders dan = kunnen niet worden gebruikt in het onderdeel locatieaanduiding. Het volgende is wel toegestaan: query= authority="Gelderland" and keyword all "bedrijf toep*" maar het volgende mag bijvoorbeeld niet: Pagina 29 van 36


query= organisatie = "Arnh*" and organisatietype = "Gemeente" Sortering De zoekresultaten worden standaard gesorteerd op relevantie. Deze wordt bepaald op basis van het voorkomen van zoektermen in de metadata. Hoe vaker een term voorkomt, hoe hoger de relevantie. Als een term bij fulltext search voorkomt in het 'title' veld, komt dit resultaat hoger in de resultatenset dan wanneer het slechts in een ander veld voorkomt. Naast relevantie is het mogelijk om te sorteren op mutatiedatum ('modified'), zowel oplopend als aflopend door gebruik van 'sortby', bijvoorbeeld: ((keyword=gemeente) sortby modified/sort.descending) ((keyword=gemeente) sortby modified/sort.ascending)

4.2.3

Character escaping In SRU is een “&” een gereserveerd teken om parameters te scheiden. Wanneer gezocht moet worden op een string met een “&” erin, vervang deze dan door middel van character escaping %26. Spaties %20 , aanhalingstekens %22 en ronde haken %28 en %29 mogen vervangen worden maar dit is niet noodzakelijk. Voorbeeld van een zoekvraag met de string Bergen (NH): query= authority="Bergen%20%28NH%29"

4.2.4

Zoeken in velden De zoekcriteria hebben betrekking op de velden in de collectie, zoals beschreven in hoofdstuk 3. De onderstaande velden kunnen gericht worden doorzocht. In de CQL query kan volstaan worden met de naam zonder namespace prefix, bijvoorbeeld 'title=Paspoort'. Naast het zoeken in specifieke velden is uiteraard ook full-text-zoeken mogelijk met het zoekcriterium 'keyword'. Hierdoor wordt gezocht in meerdere velden, zoals in de tabel aangegeven.

Veld

Fulltext zoeken

title

ja

abstract

ja

modified subject

Opmerkingen

Gebruik van ==, =, <, >, <= en >= toegestaan ja Pagina 30 van 36


audience

Waarden: ondernemer of particulier

language

Conform encoding scheme, zie H2

identifier productID onlineAanvragen

Waarden: ja, nee of digid

aanvraagURL eenmaligAanmelden authority

ja

Tekstuele waarde, conform waardelijsten, zie H2, bijvoorbeeld Abcoude

organisatieType

Waarden: Gemeente, Waterschap, Provincie, GGD, Ministerie, AndereOrganisatie (met hoofdletter)

spatialType

Waarden: Gemeente, Waterschap, Provincie, GGD, Koninkrijksdeel (met hoofdletter)

uniformeProductnaam

Tekstuele waarde, conform waardelijsten, zie H2, bijvoorbeeld evenementvergunning

gerelateerdProduct

Tekstuele waarde, conform waardelijsten, zie H2, bijvoorbeeld evenementvergunning

productHTML 4.2.5

Waarden: ja of nee; kan ook leeg zijn

ja

Regionaal zoeken: uitbreiden van de zoekvraag met relevante organisaties Wanneer in de zoekvraag een (4-cijfer) postcode of gemeente als locatie wordt gespecificeerd, bepaalt de zoekdienst zelf welke organisaties relevant zijn. Dit wordt bepaald op basis van: de (commerciële) postcodetabel met relaties tussen gemeenten, (4-cijfer) postcodes en provincies. Deze postcodetabel wordt periodiek aangepast; het OWMS framework met daarin geografische relaties tussen diverse soorten organisaties. Momenteel zijn dat de relaties gemeente-waterschap, gemeente-provincie en gemeente-GGD. Deze relaties worden aangepast indien nodig. De (4-cijfer) postcode kan worden opgenomen in de CQL query, bijvoorbeeld 'postcode=5014'. De gemeente kan worden opgenomen in de CQL query als 'organisatie', bijvoorbeeld 'organisatie=”Abcoude”'. Bij aanduiding van locatie met een postcode bepaalt de zoekdienst welke gemeente het betreft, in welke provincie die ligt, welke waterschappen in Pagina 31 van 36


die gemeente actief zijn, en welke regionale organisaties op die postcode of in die gemeente actief zijn (afhankelijk van hoe de organisatie de informatie aanlevert). Bij aanduiding van locatie met een gemeentenaam bepaalt de zoekdienst in welke provincie die ligt, welke waterschappen in die gemeente actief zijn, en welke regionale organisaties in die gemeente actief zijn. Indien u zelf de content van Samenwerkende Catalogi verwerkt in uw applicatie (d.w.z. buiten de zoekdienst om), dient u zelf de koppeling met relevante organisaties te maken. In de zoekvraag kan tevens aangegeven worden van welke organisatietypen producten doorzocht moeten worden: gemeenten (organisatietype=Gemeente) provincies (organisatietype=Provincie) waterschappen (organisatietype=Waterschap) GGDen (organisatietype=GGD) ministeries (organisatietype=Ministerie) andere organisaties (organisatietype=AndereOrganisatie) Door een combinatie van locatie en organisatietype kan het zoekgebied dus nauwkeurig worden aangeduid. U dient de criteria 'postcode', 'organisatie' en 'organisatietype' aan het begin van uw CQL query op te nemen, vóór de andere criteria. Zorg ervoor dat dit gedeelte van de query omsloten wordt door haakjes. Bijvoorbeeld: query=((organisatie="Sluis" and organisatieType="Gemeente" or organisatieType="Provincie") and (keyword="paspoort")) Een voorbeeld van een CQL query met gebruik van postcode en organisatietype is: query=((postcode=4501 and organisatietype=Provincie or organisatietype=Ministerie or organisatietype=Waterschap) and (keyword="water")) Deze query geeft resultaten met de tekst 'water' van de provincie Zeeland, het waterschap Scheldestromen en van ministeries. Een vergelijkbaar voorbeeld met gebruik van gemeentenaam is: query=((organisatie="Sluis" and organisatietype=Provincie or organisatietype=Ministerie or organisatietype=Waterschap) and (keyword="water"))

Pagina 32 van 36


Indien gewenst kan ook direct gezocht worden naar producten van specifieke organisaties door te zoeken in het veld authority.

4.2.6

Het zoekresultaat Het zoekresultaat is een XML bericht conform de SRU specificaties, met daarin voor ieder gevonden record de originele (OWMS) metadata. Zie voor een concreet voorbeeld de bijlage. Als de SRU query niet begrepen wordt door de zoekdienst, of als er een fout optreedt, dan volgt in de meeste gevallen een standaard SRU foutbericht. Hierin staat nader toegelicht hoe de collectie kan worden bevraagd. Dit is een vrij eenvoudig bericht: een root element 'diagnostics' met sub-element 'diagnostic', en vervolgens een URI, details en message. Zie bijlage 3 voor een voorbeeld. Niet alle foutieve queries worden standaard afgevangen door een SRU foutbericht. Het is incidenteel mogelijk dat de zoekdienst bij een foutieve query toch resultaten teruggeeft. Dat zullen echter niet de gewenste resultaten zijn. Het XML zoekresultaat bevat een root-element 'searchRetrieveResponse' met daarin informatie over de resultatenset, een aantal 'records' en een element 'extraResponseData'. Ten behoeve van de leesbaarheid zijn de namespaces in de voorbeelden weggelaten. De generieke SRU elementen vallen in de namespace "http://www.loc.gov/zing/srw/".

<searchRetrieveResponse> 1.2 14 ... ... ... ... 11 <extraResponseData>

Pagina 33 van 36


Het element 'version' heeft betrekking op de betreffende versie van de SRU standaard. Het element 'numberOfRecords' geeft het totaal aantal gevonden resultaten weer. Dit staat los van het aantal records in het XML bericht dat wordt bepaald door gebruik van 'maximumRecords' in de query. Wordt in de zoekvraag bijvoorbeeld 'maximumRecords=10' gespecificeerd, en zijn er 14 resultaten, dan bevat 'numberOfRecords' de waarde 14. Het aantal records in het XML bericht wordt niet expliciet opgenomen, maar kan bepaald worden door het aantal 'record' elementen te tellen. Indien van toepassing wordt het element 'nextRecordPosition' opgenomen, waarmee wordt verwezen naar het eerstvolgende record in de resultatenset. In het voorbeeld zou dat 11 zijn. Het element 'extraResponseData' kan in de toekomst gebruikt worden voor extra informatie, zoals SPARQL-relaties die betrekking hebben op de gevonden resultaten. Vooralsnog hoeft een SC-afnemer hier echter niets mee te doen. Elk record element bevat informatie over het gevonden product. Deze bestaat uit een aantal generieke SRU-elementen en een aantal specifiek voor de zoekdienst:

http://standaarden.overheid.nl/sru/ xml <scproduct> ... <enrichedData> ... 1 <extraRecordData> ... Pagina 34 van 36


Het element gzd en sub-elementen originalData en enrichedData vallen onder de namespace "http://standaarden.overheid.nl/sru". Onder 'originalData' vindt u de data in OWMS-formaat zoals deze ook bij aanlevering is gestructureerd (het element 'scproduct' met alle subelementen). Hierbij wordt het dcterms:subject veld achterwege gelaten. De 'enrichedData' bevat enkele waarden specifiek ten behoeve van de zoekdienst en daarom niet relevant voor afnemers. In het element 'recordPosition' wordt de positie van het record binnen de totale resultatenset getoond. Onder 'extraRecordData' vindt u enkele extra kenmerken van het zoekresultaat. Een voorbeeld hiervan is opgenomen als bijlage. Relevant voor SC-afnemers zijn de volgende elementen, elk in een eigen namespace. Indien u wilt dat de webservice <extraResponseData> en <extraRecordData> parameters retourneert, moet de paramater “&x-info1-accept=any” aan alle queries worden toegevoegd. U krijgt dan de volgende informatie meegeleverd: version: U krijgt altijd de volledige versie terug met de originele metadata; timestamp: datum en tijd van indexatie door de zoekdienst volgens W3CDTF; rank: de relevantie van het resultaat in relatie tot de zoekvraag, uitgedrukt als percentage bijvoorbeeld: 47% . Dit veld is alleen van toepassing als gesorteerd werd op relevantie (de standaard sortering); snippet: standaard samenvatting voor de resultatenlijst accept: De mededeling dat u hebt gevraagd om alle extraRecordData terug te leveren

Pagina 35 van 36


5

Meer informatie

Alle relevante schema‟s die noodzakelijk zijn voor een goede implementatie van dit project zijn te downloaden vanaf de site http://standaarden.overheid.nl/sc/. Op de site http://www.logius.nl/samenwerkende-catalogi is het nieuwe IPM SC4.0 te vinden alsmede additionele informatie zoals nuttige FAQ‟s. Op de site van www.overheid.nl is meer informatie te vinden over de SRU zoekservice in PDF formaat: http://overheid.nl/media/downloads/SRU_webservice_van_Overheid_nl.p df Heeft uw organisatie of uw leverancier vragen over het implementatietraject, neem dan direct contact op met Servicecentrum Logius T 0900 555 4555 (10 ct p/m) [email protected] Vanzelfsprekend houden wij ons aanbevolen om commentaar te ontvangen dat bijdraagt aan een verdere verbetering van dit document. Ook als er onderwerpen zijn die in dit document niet (voldoende) zijn geadresseerd vernemen wij dat graag.

Pagina 36 van 36

Informatie Publicatie Model Samenwerkende Catalogi 4.0. Deel B: Technische Beschrijving. Versie 1.0. Datum 23 april 2012 Status Norm

Recommend Documents