Digikoppeling Koppelvlakstandaard Grote Berichten 3.8.1

Logius Standaard
Vastgestelde versie

Deze versie:
https://gitdocumentatie.logius.nl/publicatie/dk/gb/3.8.1
Laatst gepubliceerde versie:
https://gitdocumentatie.logius.nl/publicatie/dk/gb/
Laatste werkversie:
https://logius-standaarden.github.io/Digikoppeling-Koppelvlakstandaard-GB/
Vorige versie
https://gitdocumentatie.logius.nl/publicatie/dk/gb/3.8/
Redacteurs:
Peter Haasnoot
(Logius)
Auteur:
Pieter Hering
Doe mee:
GitHub Logius-standaarden/Digikoppeling-Koppelvlakstandaard-GB
Dien een melding in
Revisiehistorie
Pull requests

This document is also available in this non-normative format: pdf


Samenvatting

Dit document beschrijft de functionele specificaties voor de Digikoppeling koppelvlakstandaard Grote Berichten, onderdeel van Digikoppeling.

Het document is bestemd voor architecten en ontwikkelaars die op basis van Digikoppeling Grote Berichten gegevens willen uitwisselen. Zie onderstaande tabel bij welke taken dit document ondersteunt. Alle webservices die op Grote Berichten gebaseerd zijn, moeten conformeren aan de koppelvlakstandaard Grote Berichten. Deze wordt tot in detail in dit document gespecificeerd. Het doel van dit document is ontwikkelaars te informeren wat deze koppelvlakstandaard nu precies inhoudt en waar zij zich aan moeten conformeren. Het gaat hierbij om zowel (service) aanbieders als (service) afnemers.

Status van dit document

Dit is de definitieve versie van de standaard. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.

Het OBDO heeft op advies van het Forum Standaardisatie deze versie vastgesteld.

Documentbeheer

Datum Versie Auteur Opmerkingen
04/04/2016 3.4 Logius Referenties naar Beveiligingsvoorschriften aangepast naar nieuwe Document Digikoppeling beveiligingsvoorschrift type wsa:TO gecorrigeerd Bijlagen met voorbeelden verwijderd
01/10/2017 3.5 Logius Verwijzingen naar WS-RM verwijderd
23/08/2018 3.6 Logius RFC 2018-01 OIN in WSA:to/from
23/10/2018 3.7 Logius Verscherpingen n.a.v. onderzoek interop problemen.
06/10/2020 3.8 Logius RFC 2020-2, RFC 2020-3
11/04/2022 3.8.1 Logius Vermelding REST-API koppelvlak

Colofon

Logius Servicecentrum: Postbus 96810 2509
JE Den Haag
t. 0900 555 4555 (10 ct p/m)
e.servicecentrum@logius.nl

1. Inleiding

1.1 Doel en doelgroep

Dit document beschrijft de functionele specificaties voor de Digikoppeling koppelvlakstandaard Grote Berichten, onderdeel van Digikoppeling.

Het document is bestemd voor architecten en ontwikkelaars die op basis van Digikoppeling Grote Berichten gegevens willen uitwisselen. Zie onderstaande tabel bij welke taken dit document ondersteunt. Alle webservices die op Grote Berichten gebaseerd zijn, moeten conformeren aan de koppelvlakstandaard Grote Berichten. Deze wordt tot in detail in dit document gespecificeerd. Het doel van dit document is ontwikkelaars te informeren wat deze koppelvlakstandaard nu precies inhoudt en waar zij zich aan moeten conformeren. Het gaat hierbij om zowel (service) aanbieders als (service) afnemers.

Afkorting Rol Taak Doelgroep?
[MT] Management Bevoegdheid om namens organisatie (strategische) besluiten te nemen. Nee
[PL] Projectleiding Verzorgen van de aansturing van projecten. Nee
[A&D] Analyseren & ontwerpen (design) Analyseren en ontwerpen van oplossings-richtingen. Het verbinden van Business aan de IT. Ja
[OT&B] Ontwikkelen, testen en beheer Ontwikkelt, bouwt en configureert de techniek conform specificaties. Zorgen voor beheer na ingebruikname. Ja

1.2 Opbouw Digikoppeling documentatie

Digikoppeling is beschreven in een set van documenten. Deze set is als volgt opgebouwd:

Overzicht van de onderdelen van de Digikoppeling Standaard, de standaard is onderverdeeld in normatieve en ondersteunende onderdelen
Figuur 1 Opbouw documentatie Digikoppeling

Tekstalternatief

* Normatief document

† Ondersteunend document

1.3 Doel en scope van Digikoppeling

Digikoppeling biedt de mogelijkheid om op een gestandaardiseerde wijze berichten uit te wisselen tussen partijen. De uitwisseling tussen partijen wordt in drie lagen opgedeeld:

Digikoppeling richt zich dus uitsluitend op de logistieke laag. Deze afspraken komen in de koppelvlakstandaards en andere voorzieningen. In het geval van WUS en ebMS2 komt de logistieke laag overeen met de ‘header’ van het bericht en gaat de ‘body’ uitsluitend over de inhoud. In het geval van Digikoppeling grote berichten is een deel van de logistieke informatie opgenomen in de ‘body’ van het bericht in de vorm van gestandaardiseerde meta-data.

1.3.1 Leidend principe

De koppelvlakstandaarden dienen te leiden tot een maximum aan interoperabiliteit met een minimum aan benodigde ontwikkelinspanning.

Daarom wordt gekozen voor bewezen interoperabele internationale standaarden.

Digikoppeling maakt berichtenuitwisseling mogelijk op basis van de ebXML/ebMS2 en WUS families van standaarden inclusief de daarbij behorende verwante standaarden.

Aan te sluiten overheidsorganisaties hebben aangegeven op een uniforme manier (één stekker) te willen aansluiten aan Digikoppeling. Organisaties die beschikken over eigen middleware (ESB, Broker, Gateway) kunnen de aansluiting aan Digikoppeling, de adapters, in het algemeen realiseren via voorzieningen in die middleware.

De architectuur voor toepassing van Digikoppeling standaard is beschreven in het document “Digikoppeling_Architectuur”.

1.4 Koppelvlak & koppelvlakstandaard

Een koppelvlak is een interface die volgens standaarden de gegevensuitwisseling verzorgt. Het werken met vaste standaarden is essentieel voor een koppelvlak. Hierdoor wordt implementatie vergemakkelijkt. Ook wordt het mogelijk diverse soorten berichten door te sturen met een grote mate van interoperabiliteit, omdat via de standaard afspraken over hun inhoud gemaakt is.

Een van de belangrijkste eisen die door de overheid gesteld worden bij de inrichting van generieke voorzieningen is dat er niet veel maatwerk ontwikkeld hoeft te worden, maar dat er van “off the shelf” commercieel of OPEN geleverde software gebruik gemaakt kan worden. Voor Digikoppeling, dus voor de logistieke laag, betreft dat het niet willen ontwikkelen van software voor de adapters. Dit doel kan bereikt (benaderd) worden doordat gekozen wordt voor internationale (de jure of de facto) vastgelegde standaards, die door “alle” leveranciers interoperabel zijn geïmplementeerd.

Een andere eis is dat met name afnemers gebruik kunnen maken van één “stekker” (één logistiek koppelpunt).

1.4.1 Specificatie van de koppelvlakstandaard

De koppelvlakspecificatie beschrijft de eisen waar de adapters aan moeten voldoen om interoperabel met elkaar te kunnen communiceren.

De Digikoppeling Grote Berichten Standaard beschrijft dan ook niet de inhoud van het grote bericht. Wel richt de standaard zich op de beschrijving (metadata) van het grote bericht.

1.5 Opbouw van dit document

Hoofdstuk 1 bevat een aantal algemene inleidende onderwerpen. Hoofdstuk 2 bevat de kern van de standaard met de algemene gebruiksvoorwaarden.

Hoofdstuk 3 gaat in op het gebruik van de metadata.

Hoofdstuk 4 gaat in op de wijze waarop grote bestanden uitgewisseld worden.

Hoofdstuk 5 bevat de referenties en bijlagen.

Begrippen en afkortingen worden toegelicht in het document “Digikoppeling_Architectuur”.

Dit document en andere documentatie is beschikbaar op www.logius.nl/Digikoppeling

2. Koppelvlakstandaard Grote Berichten

2.1 Inleiding

De situatie kan zich voordoen dat een Digikoppeling bericht een grootte krijgt die niet meer efficiënt door de Digikoppeling adapters verwerkt kan worden. Ook kan het zich voordoen dat er behoefte bestaat aan het buiten de normale procesgang ('out-of-band') uitwisselen van grote hoeveelheden informatie tussen systemen. In die gevallen zal dit “grote bericht” op een andere wijze verstuurd moeten worden: middels de Digikoppeling Koppelvlakstandaard Grote Berichten. De volgende aanpak wordt dan gehanteerd:

Merk op dat het stuurbericht naast metadata ook voorzien kan zijn van inhoudelijke informatie die al nodig is bij de verwerking van het bericht.

Dit document beschrijft welke gegevens er in de metadata opgenomen moeten worden en hoe het HTTP 1.1 protocol gebruikt moet worden voor de overdracht van het grote bestand.

2.2 Nieuw in deze versie

In deze versie wordt de Digikoppeling Grote Berichten PUSH variant geïntroduceerd, naast de reeds bestaande PULL variant. We hebben ervoor gekozen de beschrijving van de PULL variant te integreren in de bestaande PUSH versie, omdat de voorwaarden en regels voor beide richtingen vrijwel identiek zijn.

2.3 Verzenden van Grote Berichten

2.3.1 Pull Principe

Het principe is dat de verzender het grote bestand aanbiedt via een Grote Berichten File Service en een bericht stuurt aan de ontvanger dat het bericht geplaatst is, de ontvanger kan het bestand vervolgens ophalen.

Uitwisseling groot bestand via Grote Berichten file service van de zender
Figuur 2 Uitwisseling groot bestand via Grote Berichten file service van de zender

In bovenstaand figuur is dit grafisch weergegeven.

  • Stap 1: De verzender verstuurt het bericht met de meta-data van het bestand, bijvoorbeeld naam, locatie, grootte etc.

  • Stap 2: De ontvanger ontvangt het bericht met de meta-data, en download en verwerkt vervolgens het bestand (PULL).

Opmerking
De verzender maakt hiervoor het te verzenden bestand gereed , eventueel wordt dit in meerdere delen gesplitst als dit wenselijk is.

2.3.2 Push Principe

Het principe is dat de verzender het grote bestand aanbiedt aan de Grote Berichten File Service van de ontvanger (via een upload) en een bericht stuurt aan de ontvanger dat het grote bestand verstuurd is, de ontvanger kan het bestand vervolgens verwerken.

Uitwisseling groot bestand via Grote Berichten file service van de ontvanger
Figuur 3 Uitwisseling groot bestand via Grote Berichten file service van de ontvanger

In bovenstaand figuur is dit grafisch weergegeven.

  • Stap 1: De verzender verstuurt het grote bericht naar de Grote berichten File service van de ontvanger.

  • Stap 2: De verzender verstuurt het bericht met de meta-data van het bestand, bijvoorbeeld naam, locatie, grootte etc.

Opmerking
De verzender maakt hiervoor het te verzenden bestand gereed, eventueel wordt dit in meerdere delen gesplitst als dit wenselijk is.

2.4 Gebruiksvoorwaarden

Voor het gebruik van het Digikoppeling Koppelvlakstandaard Grote Berichten gelden onderstaande algemene eisen:

Referentie Specificatie
VW000 Partijen MOGEN bilateraal overeen komen bij welke MiB berichtomvang de standaard Grote Berichten van toepassing is of dat volstaan kan worden met een gewone Digikoppeling uitwisseling sec
Een harde grens voor de berichtomvang is lastig te bepalen en in praktische zin is er sprake van overlap. Daarom is er voor gekozen dat partijen bilaterale afspraken kunnen maken waarin afgeweken wordt van de genoemde grens onder VW001, met dien verstande dat door het bilateraal karakter het nooit als argument gebruikt kan worden om andere organisaties te verplichten hieraan te voldoen.
VW001 Als partijen niet tot overeenstemming komen MOETEN zij berichten groter dan 20 MiB via het Koppelvlak Grote Berichten afhandelen.
Niet elke ontvanger is in staat om grote berichten te ontvangen (en te verwerken). Daarnaast dient te worden voorkomen dat grote berichten het transactionele berichtenverkeer eventueel zouden kunnen verstoren. Daarom dient ten aanzien van de omvang een harde grens te worden afgesproken.
VW002 Voor de overdracht van metadata MOET gebruik gemaakt worden van Digikoppeling, zoals aangeven in het hoofdstuk Metadata in dit document.
VW003 Voor de overdracht van grote bestanden MOET gebruik gemaakt worden van het mechanisme zoals aangeven in het hoofdstuk Bestandsoverdracht in dit document.

3. Metadata

De metadata beschrijft de informatie over het bestand dat verstuurd wordt met HTTP 1.1. De metadata zelf wordt verzonden via een (WUS/ebMS/API) Digikoppeling Koppelvlak

3.1 Functionele beschrijving

De onderstaande regels zijn van toepassing.

Referentie Specificatie
MD000 Metadata MOET verstuurd worden middels een Digikoppeling bericht.
MD001 De metadata XML-structuur MOET voldoen aan het XML schema in hoofdstuk Metadata XML Schema Definitie. De metadata kan een op zichzelf staand bericht zijn, maar ook een deel van een groter bericht. Het is daarbij ook toegestaan om meerdere grote bestanden in een bericht op te nemen; voor ieder afzonderlijk bestand dient dan afzonderlijk metadata in het bericht te worden opgenomen.
MD002 Voor ieder groot bestand MOET een unieke URL gegenereerd te worden; deze URL dient gebruikt te worden om het betreffende bestand op te halen. De URL is dus uniek voor het gehele Digikoppeling domein en wordt in het meta-bericht via het element <location> verstrekt aan de ontvanger. Bij een pull wordt hier <senderUrl> gevuld en bij push wordt hier <receiverUrl> gevuld. Door aan ieder bestand een unieke URL toe te kennen kan gegarandeerd worden dat het meta-bericht altijd aan het juiste bestand refereert. Het is wel toegestaan om hetzelfde bestand meerdere keren te verzenden (meerdere ontvangers); iedere ontvanger ontvangt dan wel een eigen meta-bericht, maar de URL verwijst dan telkens naar hetzelfde bestand. Ook is het toegestaan om meerdere unieke URL’s naar hetzelfde bestand te laten verwijzen.
MD003 De metadata MAG het moment aangeven (datum/tijd) waarop het grote bestand beschikbaar zal zijn (element <creationTime>) ALS dit veld ontbreekt of het moment ligt in het verleden MOET het bestand, uiterlijk op het moment dat de metadata verzonden wordt, beschikbaar zijn.
MD004 De metadata MAG het moment aangeven tot wanneer het grote bestand beschikbaar zal zijn. Het grote bestand MOET dan tenminste beschikbaar zijn tot het moment dat in de metadata aangegeven wordt (element <expirationTime>) na dat moment is de beschikbaarheid van het bestand niet meer gegarandeerd. Door een beperking op te leggen aan de beschikbaarheid wordt voorkomen dat het niet duidelijk is wanneer de betreffende bestanden weer mogen worden verwijderd.
MD005 De metadata MOET aangeven hoe groot het bestand is, uitgedrukt in het aantal bytes (element <size>). Indien met deelbestanden wordt gewerkt: de metadata MOET aangeven hoeveel deelbestanden het zijn, hoe groot elk van de deelbestanden is zijn en hoe groot het totale bestand is Door de omvang van een bestand vooraf ter beschikking te stellen kunnen de benodigde resources al vooraf gepland worden.
MD006 De metadata MOET een checksum geven van het bestand (element <checksum)>. Indien met deelbestanden wordt gewerkt: de metadata MOET een checksum geven van het totale bestand (element <checksum>). Deze checksum dient te worden weergegeven als een string van hexadecimale digits.
Toegestane algoritmen zijn: MD5, SHA-1, SHA256, SHA384, SHA512.
Aanbevolen algoritmen zijn: SHA256, SHA384, SHA512.

Door een checksum toe te voegen kan de inhoud van een bestand na de overdracht geverifieerd worden.
(De toepassing van deze algoritmen is hier gericht op (en beperkt tot) detectie van transmissiefouten mbv een checksum. MD5 en SHA-1 zijn daarom in deze context en in verband met backwards compatibiliteit opgenomen als toegestaan).
MD007 De metadata MOET de naam van het bestand opgeven, als string, met een lengte van maximaal 200 karakters (element <filename>). De toegestane karakters zijn letters, cijfers, punt, underscore, en hyphen. De naam van het bestand moet uniek zijn in de context van de uitwisseling tussen twee partijen (OIN verzender – OIN ontvanger). De eisen ten aanzien van bestandnamen kunnen voor ieder platform verschillend zijn; daarom kan de opgegeven bestandsnaam niet altijd als bestandsnaam aan de zijde van de ontvanger gebruikt worden.
MD008 De metadata MAG aangeven wat de context is van het Digikoppeling bericht waar het onderdeel vanuit maakt (attribuut <contextId>). Met behulp van de contextID is het mogelijk om de context van de applicatie op te nemen. Ook is het mogelijk een correlatie aan te brengen tussen het bestand en de metadata. Daarvoor moet het bestand dezelfde contextID bevatten.
MD009 De metadata MOET het Internet media type (MIME type of Content-type) specificeren van het bestand (element <contentType>) [rfc2046].
MD010 De metadata MOET bij pull de URL van de verzender (element <senderUrl> en bij push de URL van de ontvanger (element <receiverUrl>) bevatten.

In de bijlagen zijn de XML Schema definities (XSD) en XML voorbeeldberichten opgenomen.

3.2 Opbouw en structuur XML Schema definities

Om volledig backwards compatible te blijven met de vorige versie van de DK GB standaard waarin alleen het PULL principe was gespecificeerd worden voor PULL en PUSH aparte schema’s gehanteerd waarbij het PULL schema ongewijzigd is t.o.v. de vorige versie.

3.2.1 PULL Schema

Het PULL schema bevat een request bericht definitie. De DK GB PULL variant laat de invulling van de response verder vrij en definieert alleen (size error) en (checksum error) in algemene zin.

3.2.2 PUSH Schema

Het PUSH schema kent een request en een response bericht definitie.

De PUSH request biedt de mogelijkheid om eventueel aan te geven in het bericht dat het grote bestand uit meerdere onderdelen (‘parts’) bestaat.

Gebruik van de PUSH response definitie is optioneel. Partijen mogen ook overeenkomen om een eigen berichtstructuur voor de response te gebruiken. Indien het responsebericht van het PUSH XML Schema wordt gebruikt moet het volledig worden ingevuld (D.w.z. de ontvangststatus van het grote bestand en van de eventuele onderdelen zowel bij succesvolle ontvangst als bij fouten).

3.2.3 PUSH response bericht statuscodes

De volgende statuscodes zijn voorgedefinieerd in het PUSH responsebericht:

  • OK

  • FILE_NOT_FOUND

  • CHECKSUM_TYPE_NOT_SUPPORTED

  • CHECKSUM_ERROR

  • INCORRECT_FILE_SIZE

  • COMPRESSION_NOT_SUPPORTED

  • DECOMPRESSION_ERROR

  • UNKNOWN_ERROR

Zie ook de XSD’s in de bijlage.

4. Bestandsoverdracht

4.1 Functionaliteit

Bij elke bestandsoverdracht dient een bijbehorend meta-bericht via Digikoppeling te worden verzonden.

Referentie Type Specificatie
GB000 PUSH / PULL De bestandsoverdracht MOET gerealiseerd worden op basis van het HTTP protocol, versie 1.1, conform [rfc7230], [rfc7231], [rfc7232], [rfc7233], [rfc7234] en [rfc7235].
GB001 PULL Zowel de client als de server MOET de BYTE-RANGE optie ondersteunen conform [rfc7233] (i.e. Range, If-match, If-range, ETag en Content-range) [rfc7232] en [rfc7233]. De BYTE-RANGE optie wordt gebruikt om in geval van een resume onnodige hertransmissie van data te voorkomen. Hierdoor kan de voortgang van de bestandsoverdracht gegarandeerd worden. De ondersteuning van de byte ranges is niet verplicht conform de RFC maar in de Digikoppeling-context wel.
GB002 PUSH / PULL De client MOET de bestandsoverdracht initiëren door middel van een HTTP GET request (bij PULL) of een HTTP PUT (bij PUSH) conform [rfc7231].
GB003 PULL Indien de client een OK response ontvangt (200), dan kan de client het grote bestand op basis van deze response reconstrueren; eventuele eerder ontvangen bytes MOET de client daarbij negeren (of overschrijven).
GB004 PULL Indien de client een Partial Content response ontvangt (206), dan MOET de client het grote bestand op basis van deze en alle eerdere (partiële) responses reconstrueren; eventuele overlappende byte ranges MOET de client daarbij overschrijven met de laatst ontvangen data.
GB005 PULL Indien de HTTP verbinding verbroken wordt voordat het volledige grote bestand ontvangen is, en de client wil de overdracht hervatten dan MOET dit plaatsvinden door middel van een “Range” request conform [rfc7233]. De “Range” request maakt deel uit van de BYTE-RANGE optie. Indien de server byte ranges ondersteunt, dan zal deze een Partial Content response (206) naar de client sturen; indien de server geen byte ranges ondersteunt, dan zal deze een OK response sturen. De exacte response van de server is afhankelijke van eventueel aanwezige condities (if-range, if-match en if-unmodified-since) [rfc7233].
GB016 PUSH Bij elke HTTP PUT MOET het bestand aan de ontvangende kant worden overschreven.
GB017 PUSH Verzender KAN ZIP toepassen als container om de payload heen. Ook moet multipart met zip worden ondersteund. Compressie is geen vereiste of doel van ZIP. Wel een mogelijkheid.
GB018 Algemeen De verzender MOET foutherstel kunnen uitvoeren nav het response bericht. (Het response bericht dient aan te geven welke fout is opgetreden. Het GB PUSH XSD schema kent hiervoor een optioneel te gebruiken berichtstructuur – zie de voorgedefinieerde foutcodes en foutmeldingen van het GB PUSH XSD schema).

4.2 Beveiliging

Alleen de beoogde verzender en ontvanger moeten in staat zijn om een groot bestand te plaatsen of op te halen. Autorisatie moet daarom plaatsvinden aan de hand van het OIN uit het certificaat van deze partijen.

Referentie Type Specificatie
GB006 PUSH / PULL Het HTTP transport MOET beveiligd zijn met TLS. Aanbieder en afnemer ondersteunen de minimaal ondersteunde TLS encryptie algoritmen en sleutellengtes zoals beschreven in het [Digikoppeling Beveiligingsdocument]) op basis van een valide PKIoverheid certificaat [PKIoverheid Certificaten].
Meer informatie in het [Digikoppeling Beveiligingsdocument]
GB007 PUSH / PULL De minimaal ondersteunde TLS encryptie algoritmen en sleutellengtes worden beschreven in het [Digikoppeling Beveiligingsdocument].
Meer informatie in het [Digikoppeling Beveiligingsdocument]
GB008 PUSH / PULL Zowel de client als de server organisatie MOET zich authentiseren met een PKIoverheid certificaat [PKI CA], [PKIoverheid Certificaten].
De basis voor authenticatie en autorisatie in Digikoppeling is OIN. Achtergronden over dit gebruik zijn opgenomen in de Digikoppeling richtlijnen [Digikoppeling-Cert] (2-zijdig TLS).
GB009 PUSH / PULL De server organisatie MOET het transport autoriseren op basis van het OIN van een valide client certificaat [Digikoppeling-Cert].
GB010 PUSH / PULL Indien de server een HTTP request ontvangt van een niet geautoriseerd OIN (in het client certificaat) dan MOET een HTTP 403 (Forbidden) response naar de client gestuurd worden
GB011 PUSH / PULL De server moet certificaat-revocatie-lijsten (CRL) gebruiken [PKI Policy].
GB012 PUSH / PULL Het HTTPS transport MOET over poort 443 plaatsvinden.
GB019 PUSH / PULL IP whitelisting KAN worden toegepast om toegang tot de PUSH server af te schermen
GB020 PUSH / PULL Afschermen van de PUSH server KAN door toepassing van Diginetwerk

4.3 Betrouwbaarheid

De noodzaak van betrouwbaarheid is afhankelijk van de context. Indien de bestandsoverdracht een melding (bv in combinatie met ebMS2) betreft, is ook betrouwbaarheid noodzakelijk. Indien de bestandsoverdracht een bevraging (bv in combinatie met WUS) betreft, is dit niet noodzakelijk maar hoogstwaarschijnlijk wenselijk.

Voor de context van meldingen dient de client een retry mechanisme te implementeren rekening houdend met eventuele beperkte beschikbaarheid van het netwerk en/of de server (service-window).

Referentie Type Specificatie
GB013 Algemeen Voor meldingen, zoals bedoeld in de Digikoppeling architectuur, MOET een retry mechanisme toegepast worden dat rekening houdt met eventuele beperkte beschikbaarheid van het netwerk en/of de server (service-window) De specificatie van het aantal retries en tijdswindow vormt een situationeel af te spreken gegeven. Dit komt overeen met (afspraken over) de configuratie van ebMS2 implementaties.
GB014 Algemeen Indien na ontvangst de omvang van het bestand niet overeen komt met de omvang uit het meta-bericht, dan MOET de bestandsoverdracht als niet-succesvol beschouwd worden (size error).
GB015 Algemeen Indien na ontvangst de checksum van het bestand niet overeen komt met de checksum uit het meta-bericht, dan MOET de bestandsoverdracht als niet-succesvol beschouwd worden (checksum error).

5. Grote berichten bijlagen

5.1 XSD voor DK GB PULL principe

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  xmlns:tns="http://www.logius.nl/digikoppeling/gb/2010/10"
  targetNamespace="http://www.logius.nl/digikoppeling/gb/2010/10">
 <xs:element name="digikoppeling-external-data-references" type="tns:external-data-reference">
  </xs:element>
  
  <xs:complexType name="external-data-reference">
    <xs:sequence>
      <xs:element name="data-reference" maxOccurs="unbounded"
                     type="tns:data-reference" />
    </xs:sequence>
    <xs:attribute name="profile" type="tns:gb-profile" />
  </xs:complexType>


    <xs:complexType name="data-reference">
      <xs:sequence minOccurs="1">
        <xs:element name="lifetime">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="creationTime" type="tns:datetimeType"   
                                minOccurs="0"  />
              <xs:element name="expirationTime" type="tns:datetimeType"   
                                minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="content">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="filename" type="xs:NCName" />
              <xs:element name="checksum" type="tns:checksumType" />
              <xs:element name="size" type="xs:unsignedLong" />
            </xs:sequence>
            <xs:attribute name="contentType" use="required"                                   type="xs:string"/>
          </xs:complexType>
        </xs:element>
        <xs:element name="transport">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="location">
                <xs:complexType>
                  <xs:choice>
                  <xs:element name="senderUrl" type="tns:urlType" />
                  <xs:element name="receiverUrl" type="tns:urlType" />
                  </xs:choice>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="contextId" use="optional"/>
    </xs:complexType>


  <xs:simpleType name="gb-profile" final="restriction">
   <xs:restriction base="xs:string">
      <xs:enumeration value="digikoppeling-gb-1.0" />
      <!--
        DigiKoppeling GB profiel 1 aanduiding
      -->
    </xs:restriction>
  </xs:simpleType>

 <xs:complexType name="datetimeType">
    <xs:simpleContent>
      <xs:extension base="xs:dateTime">
        <xs:attribute name="type" use="required"
                      type="xs:string" fixed="xs:dateTime" />
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

 <xs:complexType name="checksumType">
   <xs:simpleContent>
      <xs:extension base="tns:md5String">
         <xs:attribute name="type" use="required">
           <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="MD5" />
            <xs:enumeration value="SHA1" />
            <xs:enumeration value="SHA256" />
            <xs:enumeration value="SHA384" />
            <xs:enumeration value="SHA512" />          
            </xs:restriction>
           </xs:simpleType>
        </xs:attribute>
      </xs:extension>
    </xs:simpleContent>
 </xs:complexType>
    
 <xs:complexType name="urlType">
   <xs:simpleContent>
      <xs:extension base="tns:anyString">
       <xs:attribute name="type" use="required" fixed="xs:anyURI" />
     </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

 <xs:complexType name="md5String">
   <xs:simpleContent>
      <xs:restriction base="tns:anyString">
       <xs:pattern value="[0-9a-fA-F]*" />            
      </xs:restriction>
    </xs:simpleContent>
  </xs:complexType>

 <xs:complexType name="anyString">
   <xs:simpleContent>
      <xs:extension base="xs:string" />              
    </xs:simpleContent>
  </xs:complexType>

</xs:schema>

5.2 XML Voorbeeld PULL Bericht

Dit hoofdstuk presenteert een voorbeeld van de metadata van een bestand bij gebruik PULL principe

<?xml version="1.0" encoding="UTF-8"?>
<tns:digikoppeling-external-data-references
  profile="digikoppeling-gb-1.0"
  xmlns:tns="http://www.logius.nl/digikoppeling/gb/2010/10"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.logius.nl/digikoppeling/gb/2010/10/gb-meta.xsd"> 
  <tns:data-reference contextId="12345">
    <tns:lifetime>
      <tns:creationTime type="xs:dateTime">2001-12-31T12:00:00Z</tns:creationTime>
      <tns:expirationTime type="xs:dateTime">2001-12-31T12:00:00Z</tns:expirationTime>
    </tns:lifetime>
    <tns:content contentType="application/xml">
      <tns:filename>NCName</tns:filename>
      <tns:checksum type="MD5">0123456789abcdef0123456789abcdef</tns:checksum>
      <tns:size>0</tns:size>
    </tns:content>
    <tns:transport>
      <tns:location>
        <tns:senderUrl type="xs:anyURI">https://any.url/any.name</tns:senderUrl>
      </tns:location>
    </tns:transport>
  </tns:data-reference>
</tns:digikoppeling-external-data-references>

5.3 XSD voor DK GB PUSH principe

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" xmlns:tns="http://www.logius.nl/digikoppeling/gb/2020/09" targetNamespace="http://www.logius.nl/digikoppeling/gb/2020/09">
  <xs:element name="digikoppeling-external-data-references-request" type="tns:external-data-reference-request" />
  <xs:complexType name="external-data-reference-request">
    <xs:sequence>
      <xs:element name="data-reference-request" maxOccurs="unbounded" type="tns:data-reference-request" />
    </xs:sequence>
    <xs:attribute name="profile" type="tns:gb-profile" />
  </xs:complexType>
  <xs:complexType name="data-reference-request">
    <xs:sequence minOccurs="1">
      <xs:element name="compression" type="tns:compression" />
      <xs:element name="content">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="filename" type="xs:string" />
            <xs:element name="checksum" type="tns:checksumType" />
            <xs:element name="size" type="xs:unsignedLong" />
            <xs:element name="transport">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="location" type="tns:location" />
                  <xs:element name="part" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="filename" type="xs:string" />
                        <xs:element name="checksum" type="tns:checksumType" />
                        <xs:element name="size" type="xs:unsignedLong" />
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="contentType" use="required" type="xs:string" />
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="contextId" use="optional" />
  </xs:complexType>
  <xs:element name="digikoppeling-external-data-references-response" type="tns:external-data-reference-response" />
  <xs:complexType name="external-data-reference-response">
    <xs:sequence>
      <xs:element name="data-reference-response" maxOccurs="unbounded" type="tns:data-reference-response" />
    </xs:sequence>
    <xs:attribute name="profile" type="tns:gb-profile" />
  </xs:complexType>
  <xs:complexType name="data-reference-response">
    <xs:sequence minOccurs="1">
      <xs:element name="compression" type="tns:compression" />
      <xs:element name="content">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="filename" type="xs:string" />
            <xs:element name="checksum" type="tns:checksumType" />
            <xs:element name="size" type="xs:unsignedLong" />
            <xs:element name="status" type="tns:status" />
            <xs:element name="reason" type="xs:string" minOccurs="0" />
            <xs:element name="transport">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="location" type="tns:location" />
                  <xs:element name="part" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="filename" type="xs:string" />
                        <xs:element name="checksum" type="tns:checksumType" />
                        <xs:element name="size" type="xs:unsignedLong" />
                        <xs:element name="status" type="tns:status" />
                        <xs:element name="reason" type="xs:string" minOccurs="0" />
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="contentType" use="required" type="xs:string" />
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="contextId" use="optional" />
  </xs:complexType>
  <xs:complexType name="location">
    <xs:choice>
       <xs:element name="receiverUrl" type="tns:urlType" />
    </xs:choice>
  </xs:complexType>
  <xs:simpleType name="gb-profile" final="restriction">
    <xs:restriction base="xs:string">
      <xs:enumeration value="digikoppeling-gb-2.0" />
      <!-- DigiKoppeling GB profiel aanduiding -->
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="datetimeType">
    <xs:simpleContent>
      <xs:extension base="xs:dateTime">
        <xs:attribute name="type" use="required" type="xs:string" fixed="xs:dateTime" />
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="checksumType">
    <xs:simpleContent>
      <xs:extension base="tns:checksumString">
        <xs:attribute name="type" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="MD5" />
              <xs:enumeration value="SHA1" />
              <xs:enumeration value="SHA256" />
              <xs:enumeration value="SHA384" />
              <xs:enumeration value="SHA512" />
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:simpleType name="compression">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NONE" />
      <xs:enumeration value="ZIP4J" />
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="urlType">
    <xs:simpleContent>
      <xs:extension base="tns:anyString">
        <xs:attribute name="type" use="required" fixed="xs:anyURI" />
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="checksumString">
    <xs:simpleContent>
      <xs:restriction base="tns:anyString">
        <xs:pattern value="[0-9a-fA-F]*" />
      </xs:restriction>
    </xs:simpleContent>
  </xs:complexType>
  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="OK" />
      <xs:enumeration value="FILE_NOT_FOUND" />
      <xs:enumeration value="CHECKSUM_TYPE_NOT_SUPPORTED" />
      <xs:enumeration value="CHECKSUM_ERROR" />
      <xs:enumeration value="INCORRECT_FILE_SIZE" />
      <xs:enumeration value="COMPRESSION_NOT_SUPPORTED" />
      <xs:enumeration value="DECOMPRESSION_ERROR" />
      <xs:enumeration value="UNKNOWN_ERROR" />
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="anyString">
    <xs:simpleContent>
      <xs:extension base="xs:string" />
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

5.4 XML Voorbeeld PUSH Bericht

5.4.1 Data-reference-request bericht 1 (PUSH)

Hieronder volgt een voorbeeld van een Grote Berichten data-reference-request bericht voor een PDF bestand genaamd file.pdf met een grootte van 2048MB, die is ge-upload:

<gb:Digikoppeling-external-data-references-request profile="Digikoppeling-gb-4.0">
  <gb:data-reference-request>
    
    <gb:compression>none<gb:compression>
    <gb:content contentType="application/pdf">
      <gb:filename>file.pdf</gb:filename>
      <gb:checksum type="MD5">01234567890123456789012345678901</gb:checksum>
      <gb:size>2048</gb:size>
      <gb:transport>
        <gb:location>
          <gb:receiverUrl type="xs:anyURI">
            https://my.host.nl/files/file.pdf
          </gb:receiverUrl>
        </gb:location>
      </gb:transport>
    </gb:content>
  </gb:data-reference-request>
</gb:Digikoppeling-external-data-references-request>

5.4.2 Data-reference-response bericht 1 (PUSH)

Hieronder volgt een voorbeeld van een Grote Berichten data-reference-response bericht voor de PDF bestand genaamd file.pdf met een grootte van 2048MiB, die is ge-upload en gezipped Waarbij file.pdf niet is gevonden.

<gb:Digikoppeling-external-data-references-response profile="Digikoppeling-gb-4.0">
  <gb:data-reference-response>
    <gb:compression>none<gb:compression>
    <gb:content contentType="application/pdf">
      <gb:filename>file.pdf</gb:filename>
      <gb:checksum type="MD5">01234567890123456789012345678901</gb:checksum>
      <gb:size>2048</gb:size>
      <gb:status>FILE_NOT_FOUND</gb:status>
      <gb:transport>
        <gb:location>
          <gb:receiverUrl type="xs:anyURI">
            https://my.host.nl/files/file.pdf
          </gb:receiverUrl>
        </gb:location>
      </gb:transport>
    </gb:content>
  </gb:data-reference-response>
</gb:Digikoppeling-external-data-references-response>

Alle errors behalve UNKNOWN_ERROR zijn recoverable en hebben geen reason nodig.

5.4.3 Data-reference-request bericht 2 (PUSH)

Hieronder volgt een voorbeeld van een Grote Berichten data-reference-request bericht voor een PDF bestand genaamd file.pdf met een grootte van 2048MiB, die moet worden ge-upload en is gezipped in de volgende 2 zip parts:

  • file.pdf.z01 met een grootte van 1024MiB is ge-upload naar https://my.host.nl/files/file.pdf.z01
  • file.pdf.zip met een grootte van 765MiB is ge-upload naar https://my.host.nl/files/file.pdf.zip
<gb:Digikoppeling-external-data-references-request profile="Digikoppeling-gb-4.0">
  <gb:data-reference-request>
    <gb:compression>zip4j<gb:compression>
    <gb:content contentType="application/pdf">
      <gb:filename>file.pdf</gb:filename>
      <gb:checksum type="MD5">01234567890123456789012345678901</gb:checksum>
      <gb:size>2048</gb:size>
      <gb:transport>
        <gb:location>
          <gb:receiverUrl type="xs:anyURI">
            https://my.host.nl/files/
          </gb:receiverUrl>
        </gb:location>
        <gb:part>
          <gb:filename>file.pdf.z01</gb:filename>
          <gb:checksum type="MD5">12345678901234567890123456789012</gb:checksum>
          <gb:size>1024</gb:size>
        </gb:part>
        <gb:part>
          <gb:filename>file.pdf.zip</gb:filename>
          <gb:checksum type="MD5">23456789012345678901234567890123</gb:checksum>
          <gb:size>765</gb:size>
        </gb:part>
      </gb:transport>
    </gb:content>
  </gb:data-reference-request>
</gb:Digikoppeling-external-data-references-request>

5.4.4 Data-reference-response bericht 2 (PUSH)

Hieronder volgt een voorbeeld van een Grote Berichten data-reference-response bericht voor de PDF bestand genaamd file.pdf met een grootte van 2048MB, die is ge-upload en gezipped in de volgende 2 zip parts:

  • file.001.zip met een grootte van 1024MiB is ge-upload naar https://my.host.nl/files/file.001.zip
  • file.002.zip met een grootte van 765MiB is ge-upload naar https://my.host.nl/files/file.002.zip

Waarbij file.001.zip correct is geupload en file.002.zip niet is gevonden.

<gb:Digikoppeling-external-data-references-response profile="Digikoppeling-gb-4.0">
  <gb:data-reference-response>
    <gb:compression>zip4j<gb:compression>
    <gb:content contentType="application/pdf">
      <gb:filename>file.pdf</gb:filename>
      <gb:checksum type="MD5">01234567890123456789012345678901</gb:checksum>
      <gb:size>2048</gb:size>
      <gb:status>FILE_NOT_FOUND</gb:status>
      <gb:reason></gb:reason>
      <gb:transport>
        <gb:location>
          <gb:receiverUrl type="xs:anyURI">
            https://my.host.nl/files/
          </gb:receiverUrl>
        </gb:location>
        <gb:part>
          <gb:filename>file.pdf.z01</gb:filename>
          <gb:checksum type="MD5">12345678901234567890123456789012</gb:checksum>
          <gb:size>1024</gb:size>
          <gb:status>OK</gb:status>
        </gb:part>
        <gb:part>
          <gb:filename>file.pdf.zip</gb:filename>
          <gb:checksum type="MD5">23456789012345678901234567890123</gb:checksum>
          <gb:size>765</gb:size>
          <gb:status>FILE_NOT_FOUND</gb:status>
        </gb:part>
      </gb:transport>
    </gb:content>
  </gb:data-reference-response>
</gb:Digikoppeling-external-data-references-response>

Alle errors behalve UNKNOWN_ERROR zijn recoverable en hebben geen reason nodig.

6. Conformiteit

Naast onderdelen die als niet normatief gemarkeerd zijn, zijn ook alle diagrammen, voorbeelden, en noten in dit document niet normatief. Verder is alles in dit document normatief.

De trefwoorden MAG, MOET, MOETEN en MOGEN in dit document moeten worden geïnterpreteerd als in BCP 14 [RFC2119] [RFC8174] als, en alleen als deze in hoofdletters zijn weergegeven, zoals hier getoond.

7. Lijst met figuren

A. Referenties

A.1 Normatieve referenties

[Digikoppeling Beveiligingsdocument]
Digikoppeling Beveiligingsstandaarden en voorschriften. Logius. URL: https://gitdocumentatie.logius.nl/publicatie/dk/beveilig/
[PKI CA]
Toegetreden vertrouwensdienstverleners. Logius. URL: https://www.logius.nl/diensten/pkioverheid/aansluiten-als-tsp/toegetreden-vertrouwensdienstverleners
[PKI Policy]
Programma van Eisen (PKIoverheid). Logius. URL: https://www.logius.nl/diensten/pkioverheid/aansluiten-als-tsp/pogramma-van-eisen
[PKIoverheid Certificaten]
Pkioverheid certificaten. Logius. URL: https://cert.pkioverheid.nl/
[rfc2046]
Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2046
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[rfc7230]
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[rfc7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[rfc7232]
Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7232.html
[rfc7233]
Hypertext Transfer Protocol (HTTP/1.1): Range Requests. R. Fielding, Ed.; Y. Lafon, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7233.html
[rfc7234]
Hypertext Transfer Protocol (HTTP/1.1): Caching. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7234.html
[rfc7235]
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174

A.2 Informatieve referenties

[Digikoppeling-Cert]
Gebruik en achtergrond van Digikoppeling certificaten. Logius. URL: http://www.logius.nl/digikoppeling