Denne side beskriver Datafordelerens moderniserede Dataleverancespecifikation (DLS).

Referencer

Proces for ændring af DLS

Git og GitHub

Git er et versionsstyringssystem, til håndtering af filversioner. Et Git repository er en database, der indeholder alle filer, og tilhørende filhistorik, for et givent projekt.

Brugere kan arbejde på lokale kopier af repository og synkronisere ændringer med et centralt repository, hvilket muliggør effektivt samarbejde på de versionsstyrede filer.

GitHub er en webbaseret hostingplatform, der bygger på Git-versionskontrolsystemet, hvor udviklere kan gemme, dele, samarbejde om og administrere koderepositories.

For vejledning i brug af Git og GitHub, samt god praksis, henvises til [Git – What is Git?] og [GitHub].

Proces for aflevering i GitHub

Branchingstrategi

En replikeringskanal arbejder altså primært med to branches:

1. main - hvor godkendte DLS'er afleveres til Datafordelermyndigheden.
2. main/rcXXXXX - replikeringskanalens egen branch med seneste færdige DLS-version.

Ved udvikling af ny DLS oprettes midlertidigt en tredje branch navngivet efter DLS-versionsnummeret (f.eks. main/rc00123/version2.1), hvilket sikrer konsekvent navngivning på tværs af replikeringskanaler.

Fremgangsmåde

Det overordnede flow ser ud således:

1. Der oprettes ny branch af registret til at lave sine ændringer i jf. 3.1.1
2. Registret ligger sine ændringer op i branchen og udfører egen validering af filerne
3. Registret opretter en pull-request med KDS som reviewer
4. KDS reviewer / godkender og merger herefter ind i main-branchen hvis ændringerne godkendes.

DLS-Historik

Historik for registrenes DLS’er tilgås via commit-historikken i [Datafordeler Repository].

DLS Validator – Værktøj til validering af DLS

For at automatisere og standardisere DLS-valideringsprocessen stiller Datafordeleren kommandolinjeværktøjet DLS Validator til rådighed for registre og andre aktører, der udarbejder DLS'er. Dette muliggør, at en DLS-ansvarlig selv kan kvalitetssikre og kontrollere, at en given DLS overholder de påkrævede standarder defineret af Datafordeleren (se sektion 5), før DLS'en sendes til Datafordeleren. Dermed kan udviklingstiden for nye DLS-versioner reduceres.
DLS Validator er et kommandolinjeværktøj, som validerer indholdet af Dataleverancespecifikationer (DLS'er), så dataintegritet og konsistens sikres, og dermed letter arbejdsgangen med at udvikle nye DLS'er.
Værktøjet validerer en række obligatoriske og valgfri komponenter af DLS'en, bl.a.:

• DLS-mappestruktur: Sikrer, at alle påkrævede mapper og filer er til stede.
• Datamodel (XSD- og XMI-filer): Sikrer at filerne er syntaktisk korrekte og fuldt deklarerede, samt at der er overensstemmelse mellem XSD- og XMI-definitioner.
• Distributions-bilag: Validerer diverse JSON-fil bilag mod angivne skemaer for at sikre korrekt formatering og indhold, samt overensstemmelse med datamodellen.

Adgang til værktøjet

DLS Validator, brugervejledning og tilhørende kildekode er tilgængelige via [Datafordeler_DLS_Validering Repository]. Bemærk at repository ikke er offentligt tilgængeligt, hvorfor adgang skal indhentes ved Datafordelermyndigheden. For at tilgå repository kræves en GitHub-bruger. Når GitHub-brugeren er oprettet, kan rettigheder til at se repository opnås ved at kontakte Datafordelermyndigheden.

Indhold af den moderniserede Dataleverancespecifikation

DLS'en er overordnet defineret af en hierarkisk mappestruktur, som versionsstyres i et Git repository. Repository indeholder en mappe for hvert register, som indsender og distribuerer data via Datafordeleren. Register-mapperne følger en veldefineret struktur og indeholder en række påkrævede og valgfri bilag, som Datafordeleren skal bruge for at modtage og distribuere data.
De følgende afsnit beskriver mappestrukturen, mappernes indhold og bilagenes skemaer, samt vejleder om deres udfyldelse.
Bilag i Datafordelerens DLS er primært maskinlæsbare JSON-filer, der kan valideres mod et tilhørende JSON-skema. Et JSON-skema kan definere komplekse objekter, påkrævede felter, gyldige værdier, etc. Den formelle definition via JSON-skemaet sikrer ensartet udfyldelse og letter validering af bilag.
Bemærk:

• Ikke alle bilag er påkrævede.
• Et JSON-objekt med påkrævede felter er ikke nødvendigvis i sig selv påkrævet. Med andre ord skal objektet være udfyldt korrekt, hvis det er angivet, og ellers ikke.

Overordnet mappestruktur

Datafordelerens repository har nedenstående, overordnede mappestruktur.

<Repository rodmappe>

• Guides
• Register
  • <Navn på register>
    • General
      • DLS_metadata.json
    • <Replikeringskanal ID>
      • 1. Bitemporality
      • 2. Datamodel
      • 3. Security
      • 4. Tabular_data
      • 5. Raster_data

Mappe: Guides

Mappen "Guides" indeholder alle vejledninger til, hvordan bilagene i DLS'en udfyldes. Dette inkluderer både en beskrivelse af strukturen for bilagene, samt eksempler på hvordan disse udfyldes. Der er ingen bilag i denne mappe, der skal afleveres til Datafordelermyndigheden, som del af DLS'en, da filerne heri blot er vejledninger.

Mappe: Register

Denne mappe indeholder en mappe for hvert register, som indsender og distribuerer data via Datafordeleren.

Mappe: Register / <Replikeringskanal ID>

Registrets mappe organiserer de bilag, som registret har udfyldt, per replikeringskanal. Et register kan have flere replikeringskanaler og de påkrævede bilag skal være udfyldt for hver kanal.

Mappe: Register / General

General-mappen skal indeholde følgende påkrævede, maskinlæsbare bilag:

• DLS_metadata.json, som bl.a. beskriver den DLS-format version, som registrets DLS og bilag følger.

Derudover kan et register i denne mappe specificere detaljer om registerets data, som ikke hører til i de øvrige mapper. Eksempler på bilag, hvis indhold hører hjemme i denne mappe er:

• Generelle detaljer, som gælder på tværs af flere replikeringskanaler, hvis dette er tilfældet for et register.
• Særlige forretningsregler, der har indflydelse på datadistribution samt eventuelle implementeringsdetaljer. Eksempelvis CPR og CVR's implementeringsdetaljer.
• Der understøttes udelukkende at der ligges maskinlæsbare formater (fx JSON og XML) samt Word-filer. Excel dokumenter understøttes ikke.

Bilag: DLS_metadata.json

Bilaget angiver hvilken version af DLS-formatet, den pågældende DLS følger – ikke registrets egen versionering af deres DLS. Ved idriftsættelse af den moderniserede Datafordeler, vil DLS-formatets version være "2.0".

Bilaget er formelt beskrevet af JSON-skemaet: DLS_Metadata_Schema.json.

Filens brug til versionering er yderligere beskrevet i afsnit 6.1.

Mappe: <Replikeringskanal ID>

Replikeringskanal-mappen indeholder en række undermapper, beskrevet i dette afsnit, som indeholder de maskinlæsbare bilag, der definerer den pågældende replikeringskanals distribution af data via Datafordeleren.
Mappen navngives efter formatet: "rc<numerisk id, prefikset med 0, op til 5 cifre>". F.eks. "rc00001"

Mappe: 1. Bitemporality

Mappen er tiltænkt bilag, der beskriver replikeringskanalens bitemporale model. Eksisterende registres bitemporale model er veldefinerede i Datafordeleren. Et nyt register vil være nødsaget til at indlevere bilag, der specificerer den bitemporale model.
Bemærk: Dette er ikke aktuelt for UL2 men kommer senere med UL3-leverancen.

Mappe: 2. Datamodel

I Datamodel-mappen placeres de bilag, der definerer replikeringskanalens logiske- og fysiske datamodel. Den fysiske datamodel specificeres i en XSD-fil, mens den logiske datamodel specificeres i en XMI-fil. Der er i øjeblikket ingen krav til navngivning af filerne.

Tabel 3 Bilag i mappen "2. Datamodel".

Bilag: Fysisk datamodel (XSD)

Den fysiske datamodel specificeres i en XSD-fil, der beskriver hvordan data ser ud på indlæsnings- og distributionstidspunktet.
XSD-filen indeholder:

• Entiteter, som også er specificeret i den logiske datamodel (XMI), som enten simple eller komplekse data-typer.
• Entitets-felter med dokumentation, begrænsninger (minimum- og maksimum værdier, minimum og maksimum forekomster, etc.) og UUID-reference til den logiske datamodel.

Eksempel på UUID angivelse:

<xs:annotation>
<xs:appinfo>EAID_B4EB6CD9_K545_9c37_A782_84B303BDE25A</xs:appinfo>
</xs:annotation>

Eksempel på angivelse af begrænsninger som en del af <xs:element> linjen:

<xs:element name="navnPåElement" type="xs:string" minOccurs="0" maxOccurs="1">

Bilag: Logisk datamodel (XMI)

Den logiske datamodel specificeres i en XMI-fil, der definerer egenskaber og datatyper for entiteter, samt deres indbyrdes relationer. Alle elementer, attributter og relationer identificeres med UUID.
Filen indeholder følgende:

1. Entiteter
2. Relationer (interne og til andre registres entiteter)
3. Entiteternes felter
   1. Forretningsmæssig betydning af felterne
   2. Attributter
4. Datatyper på felter
   1. Udfaldsrum for kodelister
   2. Metadata på felter

Mappe: 3. Security

I Security-mappen beskrives et registers sikkerhedsmodel. Sikkerhedsmodellen specificeres i én fil, som beskriver hvilket sikkerhedsniveau der er påkrævet, for at tilgå registerets forskellige entiteter via Datafordeleren. Datafordeleren opererer med tre sikkerhedsniveauer.

Ved udfyldelse af bilaget kan sikkerhedsniveauet specificeres på to niveauer:

• DefaultSecurity: Gælder alle entiteter.
• SpecificSecurity: Angiver entitetsspecifikke værdier og har forrang over DefaultSecurity.

Mindst én af ovenstående skal angives i bilaget. Hvis DefaultSecurity ikke er udfyldt, skal SpecificSecurity være udfyldt for mindst ét sikkerhedsniveau.
Følgende Tabel 5 fremviser eksempler for mulige kombinationer af DefaultSecurity og SpecificSecurity udfyldelse.

Bilaget er ydermere beskrevet formelt i JSON-skemaet: Security_model_Schema.json som findes i [Datafordeler Repository].

Bemærk: Hvis et register ikke bruger DefaultSecurity og ikke har beskrevet alle entiteter vha. SpecificSecurity, så vil de antages at have et Security Level 1.

Mappe: 4. Tabular_data

Registre, som indsender og distribuerer tabulære data via Datafordeleren, skal for den pågældende replikeringskanal vedlægge bilag i Tabular_data-mappen, der beskriver hvordan data skal distribueres via Datafordelerens distributionstjenester, dvs. prædefinerede og prægenererede fildownloads.

Bemærk at vektordata også betragtes som tabulær data.

Bilag: Automated_Predefined_Filedownloads.json

Bilaget definerer hvilke fildownloads Datafordeleren skal inkludere i de autogenererede distributionstjenester.
For hver entitet specificeres:

• Adgangsrettigheder.
• Opdateringsfrekvens.
• Type (delta/total).

Angives entitetsnavn som "All", gælder indstillingerne for alle registerets entiteter.
Bilaget er formelt beskrevet i JSON-skemaet: Automated_Predefined_Filedownloads_Schema.json.

Automated_Predefined_Filedownloads-bilaget består således af en liste af objekter med felter som beskrevet i nedenstående tabel.

Hvis der ikke skal distribueres prædefinerede fildownload udfyldes bilaget blot med en tom liste.

Eksempler på udfyldelse af filen fremgår i følgende tabel.

Bilag: Automated_Pregenerated_Filedownloads.json

Bilaget definerer hvilke prægenererede fildownload som registeret afleverer til Datafordeleren.
For hvert prægenereret fildownload angives et filnavn, sikkerhedsniveau og filformat, hvis registret ønsker denne type distribution.
Bilaget er formelt beskrevet af JSON-skemaet: Automated_Pregenerated_Filedownloads_Schema.json.
Automated_Pregenerated_Filedownloads bilaget består således af en liste af objekter med felter som beskrevet i Tabel 8.

Eksempel på udfyldelse ses i følgende Tabel 9.

Mappe: 5. Raster_data

Registre, som indsender og distribuerer rasterdata via Datafordeleren, skal for den pågældende replikeringskanal vedlægge bilag i Raster_data-mappen, der beskriver hvordan data skal distribueres via Datafordelerens distributionstjenester, dvs. prægenererede fildownload.

Bilag: Automated_Pregenerated_Filedownloads.json

Bilaget definerer hvilke prægenererede fildownload som registeret afleverer til Datafordeleren.
For hvert prægenereret fildownload angives et filnavn, sikkerhedsniveau og filformat, hvis registret ønsker denne type distribution.
Bilaget er formelt beskrevet af JSON-skemaet: Automated_Pregenerated_Filedownloads_Schema.json.
Automated_Pregenerated_Filedownloads bilaget består således af en liste af objekter med felter som beskrevet i Tabel 10.

Eksempel på udfyldelse ses i følgende Tabel 11.

Versionering

Filer versioneres automatisk gennem Githubs indbyggede versionsstyring. Versionering af maskinlæsbare formater bruger Git´s indbyggede versionering. Ændringer i disse filer kan således findes ved at bruge Git diff funktionaliteten direkte i ens lokale kommandoprompt eller ved at finde filen i Github og kigges på tidligere commits.

Git diff (funktionalitet til at se forskel på to filer)

1. Navigér til repositoriet på din computer
   1. cd sti/til/mappen
2. Se commits
   1. Git log –oneline
3. Vælg forskel mellem to commit hashes
   1. git diff <commit_hash_1> <commit_hash_2> --filsti/til/filen/man/fil/se/forskel/på

Verificering via Github (Mere visuel vej til at se forskel)

1. Naviger til *\[Datafordeler Repository\]*

2. Find filen du vil se ændringen på
3. Se eksempelvis Figur 4.

Eksempler på bilag der versioneres således:

• JSON
• XML

Versionering af ikke-maskinlæsbare filer gennem Githubs versionsstyring understøtter ikke at man kan tjekke forskelle mellem versioner via eksempelvis Git diff. Dette kan eksempelvis gøres for Word-dokumenter udenfor Git.

Versionering af DLS gennem DLS_metadata.json bilag

Bilaget angiver hvilken version af DLS-formatet, den pågældende DLS følger – ikke registrets egen versionering af deres DLS. Ved idriftsættelse af den moderniserede Datafordeler, vil DLS-formatets version være "2.0".
Hvis der tilføjes / fjernes bilag fra DLS'en i fremtiden, bruges dette til at være bagud kompatibelt. Datafordeleren øger versionsnummeret, når en ny DLS-format version kommer ud. Dette skal registrene tilføje som værdi i deres DLS_metadata.json bilag.

Versionering af datamodel

Når et register ændrer i dets datamodel, kan det håndteres ved enten at oprette en replikeringskanal eller opdatere den eksisterende.

Opdatering af eksisterende replikeringskanal

Når et register ændrer i dets datamodel, skal registeret aflevere følgende bilag, som bruges til at generere services:

1. XSD for nuværende datamodel (As-is XSD) samt tilhørende XMI.
   1. XSD'en specificerer dataformatet af den nuværende datamodel. Den tilhørende XMI beskriver dens relationer. Disse filer blev brugt til at generere den nuværende version af services og fildownloads.
2. XSD for kommende datamodel (To-be XSD) samt tilhørende XMI.
   1. XSD'en specificerer dataformatet af den opdaterede datamodel. Den tilhørende XMI beskriver dens relationer. Disse filer vil blive brugt til at generere den opdaterede version af services og fildownloads.
3. XSD for data-replikering (Replication XSD).
   1. XSD-filen beskriver dataformatet som registret vil replikere til Datafordeleren i transitionsperioden
   2. Replikerings-XSD-skemaet skal specificere type- og elementbegrænsninger, der er gyldige for den strengest mulige fortolkning af datavaliditet som defineret i både nuværende (as-is) og kommende (to-be) skemaer.
   3. Eksempel på data-replikerings-XSD begrænsning
      1. Hvis et register har specificeret at en specifik streng har en max længde på 250 karakterer i deres as-is XSD og deres to-be XSD har specificeret for samme streng en max længde på 500 karakterer, så skal replikering XSD'en begrænse max længden til 250 karakterer under transitionsperioden. Efter udfasningsperioden er slut, kan as-is XSD'en blive fjernet fra registrets DLS og data-replikering XSD'en kan blive ændret til to-be XSD skemaet. Herefter kan registret bruge de eventuelle nye regler fra as-is XSD'en (den tidligere to-be XSD). I stedet burde registret tilføje et nyt felt.
4. Et regelsæt der beskriver hvordan XSD-skemaet for data-replikering oversættes til den nuværende (As-is XSD) samt kommende (To-be XSD).
   1. Det er tilladt at udelade entiteter, felter og typer fra XSD-skemaet for data-replikering, som ikke eksisterer i de andre skemaer.
   2. Det er tilladt at omdøbe entiteter og felter mellem datamodel-versioner.
   3. Det er ikke tilladt at ændre felter. I stedet skal et register specificere et nyt felt som er fyldt med konverteret data fra det eksisterende felt. Efter perioden for afskrivning af nuværende, bliver det gamle felt slettet og det nye felt kan omdøbes hvis det er nødvendigt.

Så længe der er paralleldrift på flere versioner af samme datamodel, vil det være påkrævet af et register at aflevere XSD-skemaer på de datamodeller der driftes. Dette betyder også, at hvis et register har paralleldrift på 3 datamodeller, vil det være påkrævet af et register at aflevere tilsvarende flere XSD-skemaer. Bemærk at det ikke anbefales at have mere end 2 modeller ad gangen.

Oprettelse af ny replikeringskanal

1. Aflever DLS i Github jf. sektion 2.
2. Netcompany Forvaltning opretter ny replikeringskanal jf. eksisterende proces.

Versionering af fildownload og GraphQL-tjenester

Fildownload bliver automatisk genereret baseret på den leverede fysiske datamodel der leveres af et register. Fildownload versioneres derfor også på tværs af replikeringskanaler, hvilket vil sige at ændringer i enkelte entiteter vil forårsage en ny version af alle fildownload for den replikeringskanal, hvis ændringen indebærer at anvenderne skal lave ændringer i eget systemet for at bruge den pågældende tjeneste. Eksempelvis hvis der fjernes et felt eller en entitet. Det samme gør sig gældende for GraphQL-tjenester.