Forklaring

Open Data Contract Standard (ODCS) forklart

ODCS er en åpen standard for datakontrakter i YAML. Her er hvem som står bak, hvilke seksjoner en kontrakt har, og hvilke verktøy som leser den.

Av Steffen Sande8 min lesing

En datakontrakt beskriver hva en produsent av data lover å levere: skjema, betydning, eier, kvalitet og tjenestenivå. Du kan skrive en slik kontrakt i et format du lager selv, men da må hvert verktøy og hvert team lære nettopp ditt format. Open Data Contract Standard, forkortet ODCS, er et felles format for det samme innholdet.

Denne artikkelen forklarer hva ODCS er, hvordan en kontrakt i standarden er bygget opp, og hva du vinner på å bruke en åpen standard i stedet for et eget format.

Hva ODCS er

ODCS er en åpen og leverandørnøytral standard for datakontrakter. Den forvaltes av Bitol, et åpent prosjekt under Linux Foundation AI & Data, og er lisensiert under Apache 2.0. Bitol står også bak en søsterstandard for dataprodukter, Open Data Product Standard (ODPS).

Standarden utvikles i det åpne på GitHub, der endringer foreslås og diskuteres som såkalte RFC-er før de tas inn. Gjeldende versjon er v3.2.0. Versjonen står i selve kontrakten, i feltet apiVersion, slik at et verktøy vet hvilken utgave av standarden filen følger.

En ODCS-kontrakt er én YAML-fil. Strukturen er beskrevet i et offisielt JSON-skjema for hver versjon, og det betyr at en maskin kan sjekke om en fil er en gyldig kontrakt før noen leser den. ODCS er en av de mest brukte standardene for datakontrakter i dag.

Seksjonene i en kontrakt

En ODCS-kontrakt er delt inn i seksjoner med faste navn. Bare fire felt er påkrevd: apiVersion, kind, id og version. Resten tar du med etter behov, og en liten kontrakt kan godt starte med skjema og eier og vokse derfra.

Grunnleggende felt

Øverst i filen står feltene som identifiserer kontrakten. apiVersion angir versjonen av standarden, og kind er alltid DataContract. id er en stabil identifikator for kontrakten, mens version er versjonen av selve kontrakten, som du øker når innholdet endres. status sier hvor kontrakten er i livsløpet sitt, for eksempel draft, active eller deprecated.

Her hører også description hjemme, med underfelt for formål (purpose), tiltenkt bruk (usage) og kjente begrensninger (limitations). Det er de feltene en ny konsument leser først.

Skjema

Seksjonen schema beskriver strukturen i dataene. Den inneholder en liste med objekter, typisk tabeller, og hvert objekt har en liste med egenskaper (properties), typisk kolonner.

ODCS skiller mellom logisk og fysisk type. Den logiske typen (logicalType) er en portabel beskrivelse som string, integer, number, date eller timestamp. Den fysiske typen (physicalType) er det databasen faktisk bruker, for eksempel varchar eller uuid. Skillet gjør at samme kontrakt kan beskrive data som ligger i ulike systemer.

For hver egenskap kan du blant annet angi om den er påkrevd (required), om den er en del av primærnøkkelen (primaryKey), en beskrivelse, og en klassifisering (classification) av hvor følsomme dataene er. Relasjoner mellom tabeller kan også beskrives her.

Kvalitet

Kvalitetsregler legges i quality, enten på et helt objekt eller på en enkelt egenskap. Standarden har fire typer regler:

  • Tekst (text): en regel beskrevet med ord, for mennesker.
  • Bibliotek (library): ferdigdefinerte målinger som nullValues, duplicateValues og rowCount, kombinert med en grense, for eksempel at antall duplikater skal være 0.
  • SQL (sql): en spørring som returnerer en verdi, og en grense verdien skal holde seg innenfor.
  • Egendefinert (custom): regler skrevet for et bestemt kvalitetsverktøy.

Bibliotekreglene er de enkleste å flytte mellom verktøy, fordi betydningen er definert av standarden og ikke av ett verktøy.

Tjenestenivå

Forventninger til leveransen ligger i slaProperties. Hver linje er en egenskap med en verdi og eventuelt en enhet, for eksempel hvor ferske dataene skal være, hvor ofte de oppdateres, og hvor lenge de oppbevares.

Team og roller

team sier hvem som eier og vedlikeholder datasettet, med en liste over medlemmer og rollene deres. roles beskriver tilgang: hvilke roller som finnes for å lese eller endre dataene, og hvem som må godkjenne en tilgangsforespørsel.

Servere

servers beskriver hvor dataene faktisk ligger: type system, for eksempel postgres, og tilkoblingsdetaljene som trengs for å nå dem. En kontrakt kan ha flere servere, for eksempel én for test og én for produksjon. Det er denne seksjonen som gjør det mulig for et verktøy å koble seg til og kontrollere at dataene stemmer med kontrakten.

Støtte, pris og utvidelser

Noen seksjoner er mindre sentrale, men nyttige når kontrakten skal deles bredt. support lister kanaler der konsumenter kan få hjelp, for eksempel en chattekanal eller en sakskø. price beskriver hva dataene koster, der det er aktuelt. tags gir stikkord for søk og gruppering.

authoritativeDefinitions peker fra kontrakten eller en egenskap til en definisjon et annet sted, for eksempel et begrep i en forretningsordbok. customProperties er standardens åpning for felt den selv ikke definerer, slik at du kan legge til egne opplysninger uten å bryte formatet.

Et eksempel: kontrakten for kunde

Eksempelet under er en liten kontrakt for datasettet kunde i en nettbutikk. Der artikkelen om datakontrakter viste skjema og kvalitet for ordre, legger denne vekt på seksjonene rundt skjemaet: beskrivelse, server, eier og tjenestenivå. Filen er gyldig mot det offisielle JSON-skjemaet for ODCS v3.2.0.

apiVersion: v3.2.0
kind: DataContract
id: kunde
version: 2.1.0
status: active
description:
  purpose: Én rad per registrert kunde i nettbutikken.
servers:
  - server: produksjon
    type: postgres
    host: db.example.com
    port: 5432
    database: butikk
    schema: salg
team:
  name: Kundeteamet
  members:
    - username: kundeteam@example.com
      role: Owner
schema:
  - name: kunde
    properties:
      - name: kunde_id
        logicalType: string
        primaryKey: true
        required: true
      - name: epost
        logicalType: string
        classification: confidential
slaProperties:
  - property: latency
    value: 1
    unit: d

Kontrakten er i versjon 2.1.0 og er aktiv. Dataene ligger i skjemaet salg i en Postgres-database, og Kundeteamet er eier. Tabellen kunde har en påkrevd primærnøkkel, kunde_id, og en e-postadresse som er klassifisert som fortrolig. Tjenestenivået sier at dataene skal være høyst én dag gamle.

Legg merke til hva kontrakten ikke sier noe om. Den har ingen kvalitetsregler og ingen beskrivelse av hver kolonne ennå. Det er helt greit: kontrakten er gyldig, og den kan utvides i en ny versjon når produsent og konsumenter er enige om mer.

Hvorfor en åpen standard gir mindre innlåsing

Når kontraktene dine følger et format som bare ett verktøy forstår, er kontraktene i praksis en del av verktøyet. Vil du bytte verktøy, må du konvertere alle kontraktene, og ofte mister du noe på veien. Det gjør det dyrt å bytte, også når et annet verktøy passer bedre.

En åpen standard snur dette. Kontrakten er en fil du eier, med en struktur som er beskrevet offentlig og forvaltet av en nøytral stiftelse, ikke av en leverandør. Det har noen konkrete følger:

  • Du kan bytte verktøy uten å skrive kontraktene på nytt. Et verktøy som leser ODCS, kan lese kontraktene du allerede har.
  • Flere verktøy kan bruke de samme filene. Ett verktøy kan brukes til å skrive kontrakter, et annet til å teste dataene mot dem, og et tredje til å vise dem i en katalog.
  • Kontraktene kan leve i versjonskontroll. En YAML-fil kan gjennomgås, sammenlignes og spores i Git som all annen kode, uavhengig av hvilket verktøy som laget den.
  • Endringer i formatet skjer i det åpne. Nye versjoner av standarden diskuteres offentlig, og du kan følge med på, eller bidra til, hva som kommer.

En standard fjerner ikke alt arbeid med å bytte verktøy. Utvidelser i customProperties kan være skrevet for ett bestemt verktøy, og to verktøy kan tolke deler av standarden ulikt. Men kjernen i kontrakten, skjema, eier, kvalitet og tjenestenivå, ligger i et format som ikke tilhører noen enkelt leverandør.

Verktøy som støtter ODCS

Et åpent verktøy med innebygd støtte for ODCS er Data Contract CLI, et kommandolinjeverktøy som bruker ODCS som sitt eget kontraktsformat. Det kan blant annet:

  • lage en ny kontrakt med datacontract init
  • kontrollere at en fil følger JSON-skjemaet for standarden med datacontract lint
  • koble seg til serverne i kontrakten og teste at dataene oppfyller den med datacontract test
  • vise forskjellen mellom to versjoner av en kontrakt med datacontract changelog
  • importere en kontrakt fra et eksisterende system og eksportere kontrakten til andre formater

Data Contract CLI validerer kontrakter skrevet etter v3.2.0, og også etter de eldre versjonene v3.1.0 og v3.0.2. Dokumentasjonen nevner også Data Contract Editor, et redigeringsverktøy for å skrive kontrakter.

Vurderer du et verktøy, er det verdt å sjekke hvilken versjon av ODCS det støtter. Støtter verktøyet bare en eldre versjon, kan det hende at felt som er nye i v3.2.0, ikke blir forstått.

Hvor du kan begynne

Den enkleste måten å bli kjent med ODCS på er å skrive en kontrakt for ett datasett du kjenner godt, slik eksempelet over gjør for kunde. Start med de påkrevde feltene, skjemaet og eieren, og kontroller filen mot JSON-skjemaet, for eksempel med datacontract lint. Når den er gyldig, kan du legge til kvalitetsregler og tjenestenivå én seksjon om gangen.

Den offisielle dokumentasjonen og JSON-skjemaene for hver versjon finnes på GitHub-siden til ODCS, og nyheter om standarden publiseres på bitol.io.

Kilder