|
|
|
||
Version |
1.8 |
|
Status |
05 - Approved |
|
Godkender |
Thomas Krohn |
© Copyright 2025 Netcompany |
Forfatter |
Marcus Norton Quistgaard |
|
Dokumenthistorik
Version |
Dato |
Forfatter |
Status |
Bemærkninger |
1.0 |
27-03-2024 |
August Clement Leve |
Færdig |
Første version af dokumentet |
1.1 |
26-09-2024 |
Carl Bedrot |
Færdig |
|
1.2 |
23-10-2024 |
Carl Bedrot |
Færdig |
4.1 Automated Predefined Filedownloads: opdaterede enheder med sikkerhedsniveau 3 har enum-værdien "Special Restricted" |
1.3 |
13-11-2024 |
Mikkel Valdemar Koch |
Udkast |
Tilføjelse af afsnit 3.10 – Mappe: Sikkerhed |
1.4 |
19-11-2024 |
August Clement Leve |
Udkast |
Konsekvensrettelser som følge af UL2-release |
1.5 |
19-03-2025 |
Tobias Overlund Stannius |
Udkast |
Ændret dokument til deliverable. Omdøbt dokument fra "Moderniseret DLS-format – Hoveddokument" til "C0200 – Moderniseret DLS-format". Tilrettet hele dokumentet til UL2. |
1.6 |
21-03-2025 |
Tobias Overlund Stannius |
Udkast |
Dokument klar til review. Sendt til KDS til review. |
1.7 |
09-04-2025 |
Marcus Norton Quistgaard |
Udkast |
Opdateret jf. KDS kommentarer fra review samt review-møde. |
1.7 |
10-04-2025 |
Marcus Norton Quistgaard |
Færdig |
Opdateret jf. KDS kommentarer efter seneste review. |
1.7 |
14-04-2025 |
Marcus Norton Quistgaard |
Færdig |
Opdateret jf. KDS kommentarer efter seneste review. |
1.7 |
15-04-2025 |
Marcus Norton Quistgaard |
Færdig |
Opdateret jf. KDS kommentarer efter seneste review. |
1.8 |
15-04-2025 |
Thomas Krohn |
Færdig |
Godkendt og sat i status 05 - Approved |
Referencer
Reference |
Titel |
Forfatter |
|||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="cfdcba55-8d41-40cd-bd34-6e26af9a8208"><ac:plain-text-body><![CDATA[ |
|
[https://github.com/SDFIdk/Datafordeler |
https://github.com/SDFIdk/Datafordeler] |
KDS |
]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="396ebdc1-6c71-4ffe-8453-3f789678e033"><ac:plain-text-body><![CDATA[ |
|
[https://github.com/SDFIdk/Datafordeler_DLS_Validering |
https://github.com/SDFIdk/Datafordeler_DLS_Validering] |
KDS |
]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0a6d914f-ad22-4bfb-a876-b11be127ab31"><ac:plain-text-body><![CDATA[ |
|
[https://git-scm.com/book/en/v2/Getting-Started-What-is-Git |
https://git-scm.com/book/en/v2/Getting-Started-What-is-Git] |
Git |
]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0def05d7-30e7-46c3-981a-541e9d8112ff"><ac:plain-text-body><![CDATA[ |
|
[https://github.com/ |
https://github.com/] |
GitHub |
]]></ac:plain-text-body></ac:structured-macro> |
Indholdsfortegnelse
1 Introduktion
1.1 Målgruppe
2 Den moderniserede DLS
2.1 Proces for ændring af DLS
3 Git og GitHub
3.1 Proces for aflevering i GitHub
3.1.1 Adgang til Datafordeler Repository
3.1.2 Branchingstrategi
3.1.3 Fremgangsmåde
3.1.4 DLS-Historik
4 DLS Validator – Værktøj til validering af DLS
4.1 Adgang til værktøjet
5 Indhold af den moderniserede Dataleverancespecifikation
5.1 Overordnet mappestruktur
5.2 Mappe: Guides
5.3 Mappe: Register
5.4 Mappe: Register / <Replikeringskanal ID>
5.5 Mappe: Register / General
5.5.1 Bilag: DLS_metadata.json
5.6 Mappe: <Replikeringskanal ID>
5.7 Mappe: 1. Bitemporality
5.8 Mappe: 2. Datamodel
5.8.1 Bilag: Fysisk datamodel (XSD)
5.8.2 Bilag: Logisk datamodel (XMI)
5.9 Mappe: 3. Security
5.10 Mappe: 4. Tabular_data
5.10.1 Bilag: Automated_Predefined_Filedownloads.json
5.10.2 Bilag: Automated_Pregenerated_Filedownloads.json
5.11 Mappe: 5. Raster_data
5.11.1 Bilag: Automated_Pregenerated_Filedownloads.json
6 Versionering
6.1 Versionering af DLS gennem DLS_metadata.json bilag
6.2 Versionering af datamodel
6.2.1 Opdatering af eksisterende replikeringskanal
6.2.2 Oprettelse af ny replikeringskanal
6.3 Versionering af fildownload og GraphQL-tjenester
7 DLS-format versioner
Dette dokument beskriver Datafordelerens moderniserede Dataleverancespecifikation (DLS).
Dokumentet er tiltænkt:
Den Moderniserede DLS vil bestå af registrets datamodel og en håndfuld maskinlæsbare bilag. På baggrund af disse vil den Moderniserede Datafordeler automatisk generere tjenester til datadistribution, herunder fildownloads, hændelser, GraphQL-tjenester og geodata-vektor-tjenester (WFS), som illustreret i Figur 1. Bemærk her at autogenerering af hændelser og geodata-vektor-tjenester (WFS) først kommer med UL3.

Figur 1: Autogenerering af datadistribution fra DLS
Efter identifikation af ændringsbehov opdateres de relevante bilag, f.eks. for datamodel, distribution eller sikkerhed, som derefter afleveres i Datafordelerens DLS GitHub repository til validering af Datafordelerens Change team (se afsnit 3.1). Når ændringerne er godkendt, implementeres de på testmiljøer og idriftsættes efterfølgende - begge dele efter aftale mellem register og Datafordelermyndighed. Processen illustreres i Figur 2.

Figur 2: Proces for aflevering af DLS til idriftsættelse af ændringer.
Ved idriftsættelsen af UL2 er følgende distributionstjenester fra registerets datamodel autogenereret:
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\]{*}. |
DLS afleveres i KDS' *\[Datafordeler Repository\]{*}, hvor DLS'en versionsstyres og interessenter kan samarbejde om ændringer. *\[Datafordeler Repository\]* er ikke offentligt tilgængelig, hvorfor GitHub-brugere, der ikke er tildelt adgang, vil blive vist en 404 fejlmeddelelse, når linket tilgås.
!worddavef897e0494a1037743c771eb3df24e05.png|height=161,width=631!
Figur 3: Adgang nægtet til GitHub fejlmeddelse
For at tilgå *\[Datafordeler Repository\]* kræves en GitHub-bruger. Når GitHub-brugeren er oprettet, kan rettigheder til at se repository opnås ved at kontakte Datafordelermyndigheden. |
{*}\[Datafordeler Repository\]* benytter en branchingstrategi, som skal sikre en stabil _Main branch_ (produktionsversion), der kun opdateres via pull requests fra replikeringskanalernes branches. Replikeringskanalernes branches navngives efter formatet main/rcXXXXX, hvor X angiver replikeringskanalens numeriske id. For hver ny DLS oprettes en separat branch fra replikeringskanalens branch, navngivet efter DLS-versionen (f.eks. main/rc00018/version2.4.5). Dette minimerer risikoen for utilsigtede ændringer i replikeringskanalens branch. Branchingstrategien er illustreret i Figur 4.
!worddavf744fb7c167b648c084ad08df5e4dc7d.png|height=274,width=631!
<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="b51989b3-0313-4e02-94be-10089c0f367c"><ac:parameter ac:name="">_Ref195093885</ac:parameter></ac:structured-macro>Figur 4: Oversigt over branchingstrategi
En replikeringskanal arbejder altså primært med to branches: |
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.
Det overordnede flow ser ud således:
Historik for registrenes DLS'er tilgås via commit-historikken i *\[Datafordeler Repository\]{*}. |
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 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. |
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:
Datafordelerens repository har nedenstående, overordnede mappestruktur.
<Repository rodmappe>
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.
Denne mappe indeholder en mappe for hvert register, som indsender og distribuerer data via Datafordeleren.
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.
General-mappen skal indeholde følgende påkrævede, maskinlæsbare bilag:
|
Krav |
DLS_metadata.json |
Bilaget er påkrævet.Filen skal være navngivet som angivet her. |
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.
DLS_Metadata_Schema.json er desuden beskrevet i Tabel 2.
Objekt |
Beskrivelse |
version_format |
En string, der beskriver det DLS-format versionsnummer, som den pågældende DLS følger og kan valideres imod. F.eks. "2.0", "2.1", "3.0". |
Tabel 2: DLS_Metadata_Schema objektet.
Filens brug til versionering er yderligere beskrevet i afsnit 6.1.
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"
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.
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.
Bilag |
Krav |
<filnavn>.xsd |
Bilaget er påkrævet. |
<filnavn>.xmi |
Bilaget er påkrævet. |
Tabel 3 Bilag i mappen "2. Datamodel".
Den fysiske datamodel specificeres i en XSD-fil, der beskriver hvordan data ser ud på indlæsnings- og distributionstidspunktet.
XSD-filen indeholder:
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">
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:
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, beskrevet i Tabel 4.
Sikkerhedsniveau |
Navn |
Beskrivelse |
1 |
Kendt bruger |
Data kan indeholde almindelige personoplysninger, som er omfattet af databeskyttelsesforordningen og databeskyttelsesloven. |
2 |
Begrænset data |
Data indeholder almindelige personoplysninger eller oplysninger, der er særligt beskyttelsesværdige, og som er omfattet af databeskyttelsesforordningen og databeskyttelsesloven. |
3 |
Specielle begrænsede data |
Data indeholder almindelige personoplysninger, følsomme personoplysninger eller oplysninger, der er særligt beskyttelsesværdige, og som er omfattet af databeskyttelsesforordningen og databeskyttelsesloven. |
Tabel 4: Sikkerhedsniveauer i Datafordeler 2.0-formatet.
Ved udfyldelse af bilaget kan sikkerhedsniveauet specificeres på to niveauer:
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.
Bilag |
Krav |
Security_Model.json |
Bilaget er påkrævet. |
<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="8269a20b-4853-43f9-9989-c9a8346fe5d1"><ac:parameter ac:name="">_Ref194996097</ac:parameter></ac:structured-macro>Tabel 5 Bilag i mappen "3. Security".
<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="05a2614b-9c36-418c-bec3-21036de950f8"><ac:parameter ac:name="">_Ref193457058</ac:parameter></ac:structured-macro>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.* |
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.
Bilaget definerer hvilke fildownloads Datafordeleren skal inkludere i de autogenererede distributionstjenester.
For hver entitet specificeres:
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 Tabel 6. Hvis der ikke skal distribueres prædefinerede fildownload udfyldes bilaget blot med en tom liste.
Objekt |
Beskrivelse |
EntityName |
String: Navnet på entiteten. Nødvendig. |
FileDownloadType |
Enumeration: Angiver, om det er et delta- eller totaldownload. Nødvendig. |
TypeOfData |
Enumeration: Angiver typen af data. Der Nødvendig.1: Current 2: Temporal3: Bitemporal |
Frequency |
Number: Angiver antallet af dage mellem generering af nyt fildownload. Nødvendig.(Der kan angives enten værdien 1 eller 7. |
SecurityLevel |
Enumeration: Angiver hvem der har adgang til data. Nødvendig. |
Tabel 6: Automated Predefined Filedownload-objektets felter.
Eksempler på udfyldelse af filen fremgår i følgende Tabel 7.
Bilag |
Krav |
Automated_Predefined_Filedownloads.json |
Bilaget er påkrævet. |
Tabel 7 Bilag Automated_Predefined_Filedownloads.json i mappen "4. Tabular_data".
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.
Objekt |
Beskrivelse |
FileName |
String: Navnet på filen. Nødvendig. |
SecurityLevel |
Enumeration: Angiver hvem der har adgang til data. SecurityLevel er beskrevet i 0 . Nødvendig. |
FileFormat |
String: Angiver filformatet, f.eks. "XML". Nødvendig. |
Tabel 8: Automated Pregenerated Filedownloads objektets felter.
Eksempel på udfyldelse ses i følgende Tabel 9.
Bilag |
Krav |
Automated_Pregenerated_Filedownloads.json |
Bilaget er valgfrit. |
Tabel 9 Bilag Automated_Pregenerated_Filedownloads.json i mappen "4. Tabular_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.
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.
Objekt |
Beskrivelse |
FileName |
String: Navnet på filen. Nødvendig. |
SecurityLevel |
Enumeration: Angiver hvem der har adgang til data. SecurityLevel er beskrevet i 0 . Nødvendig. |
FileFormat |
String: Angiver filformatet, f.eks. "XML". Nødvendig. |
Tabel 10: Automated Pregenerated Filedownloads objektets felter.
Eksempel på udfyldelse ses i følgende Tabel 11.
Bilag |
Krav |
Automated_Pregenerated_Filedownloads.json |
Bilaget er valgfrit. |
Tabel 11 Bilag Automated_Pregenerated_Filedownloads.json i mappen "5. Raster_data".
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)
Verificering via Github (Mere visuel vej til at se forskel)
Naviger til *\[Datafordeler Repository\]* |

Figur 5: Eksempel på ændring af Automated_PredefinedFiledownloads.json for CPR
Eksempler på bilag der versioneres således:
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.
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.
Når et register ændrer i dets datamodel, kan det håndteres ved enten at oprette en replikeringskanal eller opdatere den eksisterende.
Når et register ændrer i dets datamodel, skal registeret aflevere følgende bilag, som bruges til at generere services:
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.

Figur 6: Skema for generering af service til distribuering og fildownloads