Gebruik van het XML-Schema

Deze pagina beschrijft versie 0.9.8 van de Woo-metadata-standaard, het XML-schema en bijbehorende documentatie. Aan dit document kunnen geen rechten worden ontleend.

Deze pagina beschrijft hoe de XML-bestanden die voldoen aan het XML-schema (XSD) diwoo-metada.xsd gestructureerd zijn.

Structuur van de sitemap

Sitemap-protocol

De diwoo-metadata.xsd is een extensie van het sitemap-protocol. Dat betekent dat een sitemap-XML-document allereerst de sitemap-structuur volgt, met de default namespace http://www.sitemaps.org/schemas/sitemap/0.9:

<?xml version="1.0" encoding="utf-8"?>
<urlset 
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  <url><loc><!-- URL van document --></loc></url>
  <url>...</url>
  <url>...</url>
 ... 
</urlset>

Om de extensie te gebruiken moet de namespace van diwoo worden gedeclareerd. Dit kan op verschillende manieren; hieronder worden twee gebruikelijke manieren getoond.

Namespace op de root

In XML kan een namespaces aan een prefix worden gekoppeld via een namespace binding die over het algemeen aan het root-element wordt gegeven, in dit geval urlset:

<?xml version="1.0" encoding="utf-8"?>
<urlset 
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:diwoo="https://standaarden.overheid.nl/diwoo/metadata/"  
  <url><loc><!-- URL van document --></loc></url>
  <url>...</url>
  <url>...</url>
 ... 
</urlset>

De DiWoo-metadata wordt opgenomem in een kind van <url>, diwoo:Document

<?xml version="1.0" encoding="utf-8"?>
<urlset 
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:diwoo="https://standaarden.overheid.nl/diwoo/metadata/"  
  <url>
    <loc><!-- URL van document --></loc>  
    <diwoo:Document>
      <diwoo:DiWoo>
         <!-- hier de metadata van het bestand op <loc> -->         
      </diwoo:DiWoo>
    </diwoo:Document>
  </url>
  ...  
</urlset>

Namespace op element diwoo:Document

De namespace mag ook op het element diwoo:Document worden gedeclareerd; daarmee is de namespace-binding op het root-element niet meer nodig:

<?xml version="1.0" encoding="utf-8"?>
<urlset 
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"  
  <url>
    <loc><!-- URL van document --></loc>  
    <Document xmlns="https://standaarden.overheid.nl/diwoo/metadata/">
      <DiWoo>
         <!-- hier de metadata van het bestand op <loc> -->
      </DiWoo>
    </Document>
  </url>
  ...  
</urlset>

diwoo:Document

diwoo:Document is het containerelement van de metadata van het document dat op <loc> te vinden is.

Een Document kan op verschillende manieren van metadata worden voorzien:

  • diwoo:DiWoo volgens de Woo-metadata-standaard
  • diwoo:extraMetadata met naam-waarde-paren

Validatie van de sitemap

Voor zowel het standaard sitemapprotocol als voor de diwoo-extensie zijn XML-Schema's opgesteld. Aanbevelingen voor het gebruik van deze XSD's zijn:

  • Neem verwijzingen naar de internetadressen (URLs) van beide XSD's op in elke sitemap.
  • Valideer de sitemap tegen de XSD's

Neem verwijzingen op naar de XML-schema's

Een sitemap-XML-document moet voldoen aan twee XSD's:

  • de standaard sitemap.xsd en
  • de diwoo-metadata.xsd. Dit kan worden uitgedrukt door in het attribuut xsi:schemaLocation de namespaces te koppelen aan beide XSD's:
<?xml version="1.0" encoding="utf-8"?>
<urlset 
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:diwoo="https://standaarden.overheid.nl/diwoo/metadata/"  
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://www.sitemaps.org/schemas/sitemap/0.9
      http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd
    https://standaarden.overheid.nl/diwoo/metadata
      https://standaarden.overheid.nl/diwoo/metadata/0.9.8/diwoo-metadata.xsd"  
  <url>
    <loc><!-- URL van document --></loc>
    <diwoo:Document>
      <diwoo:DiWoo>
         <!-- hier de metadata van het bestand op <loc> -->
      </diwoo:DiWoo>
    </Document>
  </url>
  ...  
</urlset>

Voer validaties uit

Omdat in de sitemap verwijzingen staan naar de XSD's, kan XML-software die in staat is schema-informatie van het internet te betrekken de sitemap-XML interpreteren volgens het schema dat gebruikt is om de XML te maken. Het gaat in de context van de Woo te ver om uitgebreide informatie over XML-validatie met XSD's te beschrijven; er wordt hier volstaan met het noemen van enkele bekende XML-parsers die ingezet zouden kunnen worden in de validatie. Deze tools zijn vrij beschikbaar en kunnen relatief eenvoudig worden geïntegreerd in workflows:

  • xmllint
  • Apache Xerces
  • Libxml2
  • XSV (XML Schema Validator)
  • Saxon

Deze lijst is niet limitatief; er zijn veel andere tools beschikbaar.

Overigens hoeft de validatiesoftware niet persé direct de URLs te gebruiken om de validatie uit te voeren. Bij de diwoo-XSD's is tevens een catalog.xml beschikbaar. Dit is een XML-catalog volgens OASIS om de URLs van de XSD's te kunnen koppelen aan de gedownloade bestanden. Zo kunnen sitemaps worden gevalideerd met XSD's die op een lokale machine zonder internettoegang opgeslagen zijn.

Eigenschappen van de diwoo-metadata.xsd

Deze sectie beschrijft technische eigenschappen van de XSD zelf.

  1. Alleen diwoo:Document heeft een globale declaratie; alle andere elementen hebben géén globale maar alleen een lokale declaratie. Alléén diwoo:Document mag dienen als root-element van de extension, dus als kind-element van sitemap:url.
  2. De TOOI-URI's worden genoteerd in het attribuut @resource, de "mensleesbare" labels (rdf:Literals) zijn de inhoud van het element.
  3. Het attribuuut @resource van een beperkt aantal elementen kent een waardelijst. De waarden zijn gedeclareerd als xs:simpleTypes met xs:enumerations. Deze enumeraties komen één-op-één uit de corresponderende TOOI-waardelijsten.
  4. De waardelijstdeclaraties zijn opgenomen in een eigen bestand diwoo-metadata-lijsten.xsd. Hiermee kan, bij wijzigingen in de TOOI-waardelijsten, alléén dit XSD-bestand worden gewijzigd. Voor de referentiedocumentatie en voor validatie is het niet relevant dat deze waardelijst-declaraties in een ander bestand zijn opgenomen. De bestandsnaam is dan ook beschreven in de referentiedocumentatie.
  5. Sommige gerelateerde eigenschappen zijn verzameld in een "-collectie"-container (zoals titelcollectie of classificatiecollectie). Deze collectie-elementen kennen geen semantiek en derhalve geen tegenhanger in TOOI.
  6. De volgorde van elementen ligt niet vast in de XSD. In technische termen: er is zoveel als mogelijk gebruik gemaakt van xs:all voor "onbepaalde volgorde", en dus geen xs:sequence in de content-modellen waarin verschillende eigenschappen worden opgesomd en ook voor de "collectie"-elementen. De XSD-standaard zelf dwingt af dat er "meervouds-containers" nodig zijn voor alle elementen die meer dan ééns mogen voorkomen. Dit komt overeen met een veelgebruikt patroon voor JSON-arrays.