Een data contract legt vast welke gegevens een systeem levert, wat die gegevens betekenen en aan welke regels ze moeten voldoen. Je leest hoe teams contracten opstellen, valideren en wijzigen zonder de gevolgen voor producerende en afnemende systemen uit het oog te verliezen.
Welke afspraken horen in een data contract?
Met een data contract leg je vast hoe een producerend systeem gegevens aan andere teams aanbiedt. Alleen maar lijstjes met kolomnamen? Daar kom je niet ver mee. Je wilt weten wat voor type gegevens je krijgt, welke waarden verplicht zijn, welke waarden mogen, hoe je elk veld gebruikt en wanneer de data te verwachten is. Zo kan een afnemer risico’s inschatten, zonder te gokken wat hij veilig kan gebruiken.
Structuur, regels en context
Bijvoorbeeld: voor een tabel kan zo’n contract zeggen dat klant_id altijd gevuld is met letters en cijfers, aanmaakdatum een datum-tijd in UTC moet zijn, en status alleen gekozen mag worden uit een vaste lijst. Een event? Daarin leg je ook de naam en logica van de payload en volgorde vast. Metadata als eigenaar, bron en versie maken het simpeler om later afspraken terug te vinden.
Niet alles is zwart-wit. Een verplichte waarde kun je technisch afdwingen; hoe een veld precies werkt voor de business vraagt toch uitleg. Dus splits machineleesbare regels en uitleg voor mensen, maar houd ze wel allebei officieel bij het contract. Een schema zonder uitleg: prima voor een computer, maar een mens begrijpt dan nog niet wat een veld écht betekent. Andersom, alleen menselijke uitleg veroudert snel of wordt te ruim gelezen.
Schrijf ook op wat je niet afspreekt. Betekent de volgorde van velden iets? Als nee, zet het er expliciet bij. Wat doe je met lege waarden, of als een onbekend veld binnenkomt? Zonder die afspraken neemt ieder zijn eigen aanname; je krijgt dan onverwachte afhankelijkheden van dingen die nooit afgesproken zijn.
Gegevenstypen zijn niet hetzelfde als betekenis
Controle in een schema zegt iets over het formaat van je data: mag het tekst zijn, een getal, een datum? Maar dat vertelt nog niks over de échte bedoeling. Kijk naar het getal 12: is dat iemands leeftijd, een geboortedag, of een statuswaarde? Een datum zegt technisch niets over of het om een geboortedatum gaat, of om het moment dat een bestand verwerkt werd. Als de verzender er iets anders onder verstaat dan de ontvanger, krijg je rare resultaten ondanks geldige data.
Maak semantiek expliciet
Zet voor elk veld neer wat je bedoelt: welke eenheid hoort erbij, welk tijdvak, hoe is de waarde tot stand gekomen? Neem bijvoorbeeld een bedrag; dan wil je niet alleen het getal weten, maar óók of het in euro’s of dollars is en of BTW al is meegerekend. Tijdvelden: in UTC? En is dat de tijd van het moment zelf, of wanneer het ergens binnenkwam? Voor identifiers moet je ook aangeven: waarvan uniek?
Null betekent niet altijd hetzelfde als een lege tekst of een nulgetal. Soms is een waarde onbekend, soms niet van toepassing, soms komt het later. Meng je dit, dan gaat rapporteren of automatiseren snel de mist in.
Voor lastige business-termen: verwijs liever naar een gedeelde lijst, dan naar ‘logisch’ of ‘afspraken buiten het contract’. Zo voorkom je dat ‘actieve klant’ in systeem A iets anders betekent dan in systeem B. Je hoeft geen roman te schrijven, maar zorg dat je definities duidelijk genoeg zijn om een programmeur écht te helpen. Waar ruimte voor interpretatie overblijft, wijs je een verantwoordelijke aan: iemand bij wie je inhoudelijke vragen kwijt kunt.
Eigenaarschap van data contracts verdelen
Een data contract raakt de producer en meestal meerdere afnemende teams. Maar dat betekent niet dat iedereen eigenaar kan zijn. Als er niemand duidelijk verantwoordelijk is voor een veld, blijft bij fouten de bal liggen, omdat iedereen de ander verwacht te zien reageren. Spreek daarom af wie het totale contract bewaakt, en als dat nodig is wie per belangrijk begrip of kwaliteitseis de eerste aanspreekbare persoon is.
Producer, afnemer en platformteam
Je hebt de producer, die levert data binnen de afgesproken structuur en kwaliteitsregels. De afnemer verwerkt die data conform de afgesproken betekenis en moet melden als iets ontbreekt of onduidelijk is. Een platformteam mag best tools en support regelen voor validatie en opslag, maar hoort geen eigenaar te worden van regels of businessbetekenis. Daarmee voorkom je dat ‘de techniek’ per ongeluk over inhoudelijke keuzes besluit.
Leg vast: wie mag een wijziging doen, wie beoordeelt zo’n voorstel, en hoe wordt ruzie opgelost? Wijzigen van een statusveld: voor de producer misschien klein, maar voor een afnemer met rapportages of automatische beslissingen kan zoiets best ingrijpend zijn. Laat daarom in een register zien wie eigenaar is, waar gebruikersvragen terecht kunnen, en welke teams afhankelijk zijn. Alleen een mailadres in het schema? Daar red je het niet mee als er niemand achter zit.
Blijf eigenaarschap actueel houden, vooral als mensen vertrekken of teams veranderen. Niets zo onhandig als een contract dat alleen bestaat in iemands hoofd. Sla uitleg en toelichtingen op bij het officiële contract, zodat iedereen snapt waarom iets is afgesproken.
Validatie van data contracts in de ontwikkelketen
Een data contract is pas bruikbaar als je kunt controleren of de data er ook echt aan voldoet. Validatie kan al bij het ontwikkelen, bij het publiceren van een schema, of vlak voor opslag of verzending. Die momenten lossen ieder een eigen soort fout op: vroeg in het proces haal je ontwikkelfouten eruit, tijdens productie signaleer je afwijkingen die niet uit de code maar uit invoer of instellingen komen.
Controleer op de juiste grens
Start altijd met automatisch te checken regels: verplichte velden, types, toegestane waarden, formaat. Testen checken of je geldige én ongeldige voorbeelden krijgt. Een API-server kan bij ongeldige input gewoon "nee" zeggen; in een eventstream kan een validator berichten uitfilteren of apart wegschrijven. Welke aanpak je kiest hangt af van hoe erg het is als berichten onderweg stoppen en of je ze later makkelijk kunt herstellen.
Alleen valideren aan de producer-kant geeft geen garanties. Data kan onderweg worden aangepast, of een oude applicatie kan nog ergens draaien. Aan de ontvangende kant controleren beschermt afnemers tegen verrassingen, maar kill niet per ongeluk uitbreidbaarheid. Spreek af wat het systeem doet met onbekende velden en hoe fouten bij de juiste persoon terechtkomen.
Niet elke kwaliteitscheck is een kwestie van types. Bijvoorbeeld: een einddatum vóór de begindatum. Zulke checks vragen om extra logica. Maak onderscheid tussen schema-validatie (past het in het format?) en inhoudelijke checks (klopt het binnen de business?) zodat het duidelijk blijft wie wat moet oplossen.
Compatibiliteit tussen versies beoordelen
Een data contract leeft: systemen veranderen, en dus verandert het contract soms ook. Maar niet elke wijziging heeft hetzelfde risico. Een nieuw optioneel veld toevoegen? Vaak geen punt als afnemers extra velden negeren. Een extra verplicht veld kan juist zorgen dat bestaande berichten opeens niet meer geldig zijn. Iets verwijderen, hernoemen of van betekenis veranderen gaat meestal niet onopgemerkt, ook als aan de buitenkant weinig lijkt te veranderen.
Vooruit- en achterwaartse compatibiliteit
Achterwaartse compatibiliteit: nieuwe producers werken nog met oude afnemers. Voorwaarts: oude producers leveren data die nieuwe afnemers nog eten. Geen vanzelfsprekendheid, want strikte validatie klapt soms op onbekende velden terwijl flexibiliteit dat voorkomt.
Beschrijf in ieder contract welke compatibiliteitsregels gelden en toets elke wijziging daarnaar. Dat gaat verder dan kolomnamen en datatypes, ook beperkingen, standaardwaarden en veldbetekenis doen mee. Een bedrag ineens in euro’s in plaats van centen? Zelfde type, totaal andere inhoud. Zulke semantische wijzigingen hakken er soms flink in, meer dan een simpele schemamutatie.
Gebruik versienummers, een schema-ID of een register met beleid. Maar een versienummer alleen zegt niks; systemen moeten snappen welke versies ze pakken en hoe lang oude versies nog ondersteund zijn. Lees ook over API-versiebeheer. Test wijzigingen met echte berichten en relevante afnemers, niet alleen met het losstaande nieuwe schema.
Wijzigingen invoeren zonder afnemers te verrassen
Het doorvoeren van een contractwijziging begint bij de reden: waarom en wat precies. Misschien wil je als producer een veld hernoemen voor duidelijkheid, maar afnemers gebruiken die oude naam misschien nog volop. Check altijd eerst welke applicaties, rapportages en exports het contract gebruiken voor je aanpast. Een afhankelijkheden-catalogus helpt, maar mist soms informele koppelingen.
Geleidelijke migratie
Grotere aanpassingen? Maak een overgangsperiode. Je levert tijdelijk oud en nieuw veld naast elkaar, zodat afnemers stapsgewijs kunnen migreren. Dat maakt het proces veiliger, maar tijdelijk wel ingewikkelder. Beide velden moeten precies gedefinieerd zijn, verschillen? Zet dat in de documentatie. Anders ontstaat ruis en gebruiken verschillende systemen verschillende versies tegelijk.
Weten wanneer een afnemer over is, kan op basis van testresultaten, gebruiksdata, of gewoon een akkoord. Niet alleen weghalen omdat je een nieuwe versie hebt gemaakt; je wilt zeker weten dat je niemand onverhoopt upsets. Communiceer over wat, wanneer, waarom en welke acties nodig zijn. Een technisch changelog is zelden genoeg voor functioneel inzicht.
Als het snel moet (denk aan een spoedfix), leg dan vast wie akkoord gaf, wie geraakt kon worden en hoe teams herstel kunnen uitvoeren. Zo voorkom je dat tijdelijke noodgrepen ongezien het nieuwe normaal worden.
Contractschendingen herkennen in productie
Implementatie en validatie kunnen keurig in orde zijn en tóch kunnen in productie contractafwijkingen ontstaan. Een bron die onverwacht iets anders oplevert, een half uitgerolde update, een transformatie die niet werkt zoals bedoeld… Soms merk je dat pas als een rapportage leeg blijft of een downstream-proces uitvalt. Het zegt dus weinig als alleen het endpoint ‘up’ is, je wilt weten of de binnenkomende data klopt.
Van validatiefout naar oorzaak
Laat duidelijk zien hoeveel data in productie niet klopt, op welke regels het stukloopt en bij welke bron of versie je de afwijkingen ziet. Een enkele totaal-meter is handig, maar voor onderzoek heb je per veld en per contractversie inzicht nodig. Log foutmeldingen met veldnaam en reden, maar sla geen privacygevoelige payloads op. Met tijdstempels en eventuele correlatie-id’s maak je de trace eenvoudiger.
Per datastroom moet helder zijn wat gebeurt met foutieve data. Rejecten? Apart zetten voor herstel? Bij events kun je een errorstream gebruiken voor handmatig of automatisch herstel, zolang het maar duidelijk is wie die berichten bekijkt. Stiekem records overslaan is gevaarlijk: je merkt het probleem vaak pas als het effect heeft.
Stel meldingen af op afwijkingen met impact. Eén foutje kan toeval zijn, een plotselinge bulk duidt op een groter technisch of functioneel probleem. Bewaar genoeg context om fouten over de tijd te kunnen vergelijken, en weet wie aanspreekbaar is bij incidenten. Zo wordt een contractafwijking een echte, beheerbare gebeurtenis in plaats van alleen een melding in een log.
Data contracts toepassen op API's, events en datasets
De vorm van een data contract wisselt met het soort interface. Een API-contract behandelt aanvragen, antwoorden, foutcodes en wat er gebeurt bij missende of foute invoer. Bij events zijn de naam, sleutel, publicatiecontext en het precieze tijdstip belangrijk. Voor datasets gaat het meer om kolommen, partitionering, updatefrequentie, en wat je doet bij correcties achteraf.
Pas de afspraken aan het gebruik aan
Een event is meestal een melding dat er iets is gebeurd, geen stand van zaken. Als een orderstatus verandert van ‘verzonden’ naar ‘geannuleerd’, moet duidelijk zijn of dat een nieuwe event is of een correctie/vervanging. Let ook op duplicaten en volgorde: sommige systemen bezorgen berichten dubbel of garanderen geen volgorde.
Voor datasets is het belangrijk vast te leggen hoe vaak geüpdatet wordt en of data kan veranderen met terugwerkende kracht. Zo weten afnemers of een dagbestand definitief is of dat correcties mogelijk zijn. Bij webshopvoorraad tussen systemen synchroniseren is het bijvoorbeeld belangrijk om afspraken over updates en correcties vast te leggen. Bij API’s zijn dingen als paginering, foutcodes en optionele velden bepalend voor stabiele integratie.
Gebruik, waar handig, een gedeeld formaat voor schema’s en validatie, maar probeer niet álles in één model te persen als het niet past. Registratie op één centrale plek is handig voor vindbaarheid en eigenaarschap, maar houd per interface een contract dat precies past. Maak contracten klein en specifiek; dat maakt wijzigingen en afhankelijkheden makkelijker te beheren. Voor events beschrijft de AsyncAPI-specificatie een machineleesbaar contract. Een praktijkvoorbeeld is de Telvero-case over WooCommerce en Channable.
Veelgestelde vragen
Welk formaat gebruik je voor een data contract?
Het exacte formaat verschilt per interface en de technieken in je landschap. Werk je met JSON? Dan is JSON Schema logisch. Berichten in events of streaming? Avro en Protobuf zijn daar gebruikelijk voor. Voor API’s wordt vaak OpenAPI gebruikt. Geen enkel formaat bevat vanzelf álle zakelijke uitleg of afspraken over beheer.
- Kies waar mogelijk wat je tooling ondersteunt.
- Check of het formaat geschikt is voor validatie en versiebeheer.
- Documenteer alle zakelijke context die je niet in het schema zelf kwijt kunt.
Hoe begin je met data contracts in een bestaande dataomgeving?
Start met één concrete gegevensstroom die voor meerdere teams relevant en gevoelig is voor fouten of misverstanden. Haal de producer, voornaamste gebruikers en belangrijkste risico’s erbij. Noteer wat er nu is: welke velden, wat betekenen ze, wie is eigenaar, en wat verwachten teams precies. Leg dit samen vast en bespreek het. Zo krijg je ervaring in het klein voordat je verder uitrolt.
- Kies een gecontroleerde, overzichtelijke pilot.
- Maak aannames en uitzonderingen zichtbaar, niet alleen de standaardregels.
- Werk feedback direct in je proces in.
- Ga pas groter als duidelijk is wie de contracten gaat bijhouden.
Hoe leg je data freshness en beschikbaarheid vast in een data contract?
Je legt freshness en beschikbaarheid vast als meetbare eisen, inclusief een duidelijk afgebakend meetpunt en tijdsperiode. Schrijf op hoe vaak data wordt ververst, hoe oud records maximaal mogen zijn, en binnen welke tijd een dataset na een trigger beschikbaar moet zijn. Noteer ook hoeveel uitloop je toestaat en wat je bij gepland onderhoud doet, zodat beide kanten weten wat de norm is.
- Definieer de concrete grens, zoals tijdsvertraging of maximaal leeftijd.
- Beschrijf expliciet waar de meting plaatsvindt én wie meet.
- Spreek af wie actie onderneemt bij afwijking en hoe gebruikers worden gealarmeerd.
Hoe neem je privacyafspraken op in een data contract?
Zet in het contract welke persoonsgegevens gedeeld worden, waarom dat nodig is en onder welke voorwaarden de data mag worden gebruikt. Neem ook op: classificatie (bijvoorbeeld ‘vertrouwelijk’), wie toegang mag, hoe lang gegevens bewaard mogen blijven en eisen over verwijderen of anonimiseren. Het contract maakt een privacybeoordeling makkelijker, maar vervangt die niet.
- Deel geen velden die je niet écht nodig hebt.
- Markeer gevoelige velden en omschrijf toegangsrestricties.
- Stop geen echte persoonsgegevens in testvoorbeelden als het niet noodzakelijk is.
- Wijs een contactpersoon aan voor alle privacyvragen omtrent deze data.
Wat is het verschil tussen een data contract en een data quality SLA?
Een data contract gaat over welke gegevens je uitwisselt, hoe ze gestructureerd zijn en wat ze betekenen. Een data quality SLA legt vast aan welke meetbare kwaliteitsnormen data moet voldoen en wat er gebeurt als je daaronder zakt. Sommige onderwerpen staan in beide, zoals eisen aan actualiteit of volledigheid. Zolang het maar helder is waar elke afspraak precies is vastgelegd, kunnen contract en SLA gewoon naar elkaar verwijzen.
- Gebruik het contract voor structuur, semantiek en gebruikscondities.
- Leg afspraken over doelen, rapportages en opvolging in de SLA vast.
- Laat contract en SLA naar elkaar verwijzen, zodat niks dubbel of juist mist.
Foto: AlphaTradeZone