Denne side beskriver Datafordelerens moderniserede Dataleverancespecifikation (DLS).

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 ændringerne
2. Registret ligger sine ændringerne op i branchen og udfører egen validering af filerne
3. Registret opretter en pull-request med Datafordeleroperatøren som reviewer
4. Datafordeleroperatøren 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 Indhold af den moderniserede Dataleverancespecifikation), 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 Datafordeleroperatøren. 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 Datafordeleroperatøren.

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, som 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 / 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.

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.

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 Versionering af DLS gennem DLS_metadata.json bilag.

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.

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.

Navngivningen af filerne skal følge dette mønster:. MAJOR.MINOR.PATCH.[REGISTERNAVN jf. GraphQL schema].xmi

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

Bilag: Relations.json

Relations.json er et supplement til datamodellen og bruges til at definere relationerne mellem entiteter internt i registret og eksternt til andre registre. Bilaget er nødvendig for fleksibel opslagslogik, dvs. for at muliggøre joins mellem entiteter og udstille disse relationer.

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

Bilaget består af en liste af relationsversioner (RelationVersions). Hver RelationVersion er defineret af to egenskaber, et versionsnummer (RelationVersionNumber) og en liste af relationer (Relations). Versionering af bilaget er kompleks og er nærmere beskrevet i afsnit Versionering af Relations.

Retningslinjer for review af Relations.json

Denne vejledning forklarer, hvordan man korrekt ændrer Relations bilaget. Der er tre scenarier, hvor der er behov for at ændre i bilaget. Disse scenarier er skitseret afsnittene neden for.

Første generation af bilag

Processen og ansvar er ligeledes fordelt som for de andre bilag. Men når relations bilaget genereres første gang, sender Datafordelerleverandøren også Valideringsrapport (yderligere forklaret i afsnit Valideringsrapport) med til registret.

Den generator, der genererer bilaget, kan ikke udtrække kilde- og målfelter (”SourceField” og ”TargetField”) for relationerne, da disse ikke er defineret i XMI'erne. Derfor skal registret gennemgå hver enkelt relation i bilaget, når det modtager den autogenererede Relations.json, og angive kilde- og målfelter. Med andre ord, skal registret indtaste de felter, hvorpå JOIN-operationen skal ske for entiteterne (iflg. instruktionerne i afsnittet Fuldførelse af relation). Dette muliggør, at bilaget kan bruges til at generere en fleksibel GraphQL-tjeneste.

Derudover bør registret overveje følgende:

• Hvis der mangler relationer, som registret ellers forventede, skal disse tilføjes (i instruktionerne i afsnittet Tilføjelse af en relation). Bemærk at manglende relationer også kan skyldes fejl i den eksisterende datamodel, hvilket vil fremgå af valideringsrapporten. I det tilfælde bør de eksisterende elementer i datamodellen rettes og bilaget genereres på ny.
• Hvis der findes relationer, som registret ikke ønsker er udstillede, bør disse fjernes (i instruktionerne i afsnittet Fjernelse af en relation).

Bemærk at enhver manuel ændring i relationsbilaget, ud over at fuldføre ufuldstændige relationer, ikke repliceres af generatoren, når den køres igen. Dette skyldes, at generatoren bruger XSD'erne/XMI'erne som input og anser disse for at være autoritative. Det anbefales, at datamodellen (XMI’en) opdateres, så den afspejler alle manuelle ændringer.

Opdater datamodellen jf. ændringer i Relations.json

Når der er foretaget manuelle ændringer i Relations.json af registret (fjernelse eller tilføjelse af relationer) anbefales det, at registrets datamodel også opdateres. Dette sikrer, at fremtidige genereringer af bilaget indeholder de korrekte relationer, uden behov for yderligere manuel intervention. Generatoren bag bilaget fungerer ved at analysere elementerne <packagedElement> og <connector> i XMI-filerne. Dette betyder, at enhver manuel ændring i Relations.json bør afspejles i førnævnte elementer:

• Når en relation fjernes fra relationsbilaget, bør de tilsvarende <packagedElement> og <connector> også fjernes fra XMI-filen.

Når en relation tilføjes til relationsbilaget, skyldes det typisk, at der mangler et <packagedElement> og en <connector> i XMI-filen, som derfor bør tilføjes.

Opdatering af datamodelversion

Når en datamodelversion opdateres, skal trinene i afsnittet Første generation af bilag gentages. Det er vigtigt også at evaluere, hvordan datamodelændringerne påvirker andre registre (f.eks. hvis en entitet eller et felt fjernes/omdøbes).

Change request

Processen for at opdatere et Relationsbilag i produktion er:

• Foretag tilføjelse og eller fjernelse af relationer i bilaget.
• Opret en ny pull-request.
• Notificér Datafordeleroperatøren (ved at oprette en "Change Request" i Jira - husk at inkludere et link til pull-requesten)

Valideringsrapport

Når Relationsbilaget genereres, produceres der også en valideringsrapport til den person som starter generatoren. Hvis der er noget i datamodellen, der giver anledning til fejl eller tvivl, vil den pågældende relation ikke blive parset (dvs. den vil blive udeladt fra bilaget), og advarslen / fejlen logges i valideringsrapporten.

Følgende fejltyper fremgår af valideringsrapporten:

1. Entities from associations in XMIs missing in XSDs (association EAID, entity EAID)
   • Generatoren bruger som udgangspunkt XMI'erne for at identificere relationerne. Relationerne defineres med en kilde- og en målentitet, og hver entitet skal have et EAID. En del af valideringen består i at bekræfte, at en given kilde-entitet findes i registrets egen XSD, samt at en given mål-entitet findes i en vilkårlig replikeringskanals/registers XSD. Dette gøres ved at søge efter entitetens EAID i de pågældende XSD'er.
   • Hvis denne fejl fremgår af rapporten, betyder det, at EAID for enten kilde- eller målenheden i en relation ikke findes i nogen af XSD'erne. Risikoen er derfor, at relationen er ubrugelig og derfor er den udeladt fra bilaget.
   • For at gøre det lettere at forstå, hvilken relation der er udeladt og på grund af hvilken entitet, er EAID for både relationen og den problematiske entitet angivet.
2. Undefined Multiplicity (association EAID)
   • Meddelelsen betyder, at de oplysninger, der kræves for at bestemme feltet ”ToManyRelation”, manglede eller var forkerte for relationen med det givne EAID.
3. No Connectors Found in XMI
   • Meddelelsen betyder, at der var defineret relationer i XMI'en, men at de elementer, der indeholder information om relationerne (<connectors>), ikke er definerede.
   • Dette betyder, at ingen relationer kan parses, selvom der måske er defineret nogle i datamodellen.
4. Source not defined in association in XMI (association EAID)
   • Meddelelsen betyder, at de oplysninger, der kræves for at indstille ”SourceEntity” enten mangler eller er forkerte for relationen med det givne EAID.
5. Tag not defined in association in XMI (association EAID)
   • Meddelelsen betyder, at de oplysninger, der kræves for at indstille ”TargetEntity”, ”TargetRc” og ”TargetRcVersion” enten mangler eller er forkerte for relationen med det givne EAID.

Følgende advarsler fremgår af valideringsrapporten (for advarsel er relationer ikke udeladt):

1. Unnamed Association in XMI (association EAID)
   • Meddelelsen betyder, at relationen med den givne EAID ikke er navngivet i XMI'en.
   • Når en relation får et navn, er det det navn, der bruges til join-feltet. Når relationen mangler et navn, får relationen derimod et navn, der følger konventionen: {Kildefelt}_{Målregister}_{Målentitet}_{Målfelt}_ref.
2. No Associations Found in XMI
   • Meddelelsen betyder, at der ikke er defineret nogen relationer i XMI’en.
   • Dette kan være intentionelt. Advarslen logges for at sikre, at registret overvejer om dette er tilfældet.

Tilføjelse af en relation

En manuel relation tilføjes den seneste RelationVersion i bilaget. Hvis der er behov for at oprette en ny RelationVersion vil dette blive kommunikeret af Datafordeleroperatøren, når bilaget er blevet evalueret.

Fjernelse af en relation

Fjernelse af en relation medfører en ”breaking change”. Derfor skal der altid oprettes en ny RelationVersion i bilaget. Et eksempel er vist under Versionering af Relations.json.

Den anbefalede fremgangsmåde er at:

1. Kopiere den aktuelle RelationVersion i bilaget.
2. Øge versionsnummeret på den kopierede RelationVersion, f.eks. fra ”1” til ”2”.
3. Fjerne uønskede relationer ved at fjerne disse objekter fra Relations-listen i den kopierede RelationVersion.

Fuldførelse af relation

For at fuldføre en relation skal registret tilføje feltnavnene i de tomme pladser i relationerne for ”SourceField” og ”TargetField”. Bemærk at feltnavnene skal omgives af citationstegn (f.eks. ”NavnPåFelt”).

Følgende oplysninger er allerede udfyldt i Relations.json og kan bruges til at hjælpe dig med at udfylde felterne:

1. Kilde- og målentitet: Navnet på kilde- og målentiteten angives i relationen af felterne “SourceEntity” og “TargetEntity”. De felter, der skal udfyldes i relationen ”SourceField” og ”TargetField”, skal findes i de entiteter, som relationen er mellem.
2. Alias: Dette felt angiver navnet, som relationen har. Navnet skal angives i XMI’en under ”Alias”. Navnet er givet til det felt, der bruges til at udføre join. Kan give en idé om de felter, der er en del af relationen. Angives der ikke et Alias vil den blive autogenereret. Det skal bemærkes, at listen er omfattende, men ikke udtømmende, da der kan være foretaget ændringer i datamodellen og de tilladte joins. Derfor er oversigten kun vejledende.

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, som beskrevet neden for.

Bilaget er ydermere beskrevet formelt i JSON-skemaet: Security_model_Schema.json.

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 fremviser eksempler for mulige kombinationer af DefaultSecurity og SpecificSecurity udfyldelse.

{
    "DefaultSecurity": 1
}

{
    "SpecificSecurity": [
        {
            "SecurityLevel": 1,
            "Entities": []
        },
        {
            "SecurityLevel": 2,
            "Entities": [
                "AlternativAdresseType",
                "EjendomsadministratorType",
                "EjerskabType",
                "EjerskabsskifteType"
            ]
        },
        {
            "SecurityLevel": 3,
            "Entities": [
                "Ejerskifte_bilagsbankRefType",
                "HandelsoplysningerType",
                "PersonEllerVirksomhedsadminiType",
                "PersonVirksomhedsoplysType"
            ]
        }
    ]
}

{
    "DefaultSecurity": 1,
    "SpecificSecurity": [
      {
          "SecurityLevel": 3,
          "Entities": [
            "CVRPersonType"
          ]
      }
  ]
}

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.

Mappen ”Tabular_data” indeholder tabulære data i form af bilag, dette inkluderer også vektordata. Bilag såsom Automated Predefined Filedownload, Automated Pregenerated Filedownload og Automated WFS er I denne mappe.

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

Bilag: Automated_Predefined_Filedownloads.json

Bilaget definerer hvilke fildownload 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.

[
    {
        "EntityName": "BBRSag",
        "FileDownloadType": "1",
        "TypeOfData": "3",
        "Frequency": "7",
        "SecurityLevel": "2"
    },
(… eventuelle resterende entiteter)
]

[
    {
        "EntityName": "All",
        "FileDownloadType": "1",
        "TypeOfData": "3",
        "Frequency": "7",
        "SecurityLevel": "2"
    },
    {
        "EntityName": "All",
        "FileDownloadType": "1",
        "TypeOfData": "2",
        "Frequency": "7",
        "SecurityLevel": "2"
    },
    {
        "EntityName": "All",
        "FileDownloadType": "1",
        "TypeOfData": "1",
        "Frequency": "7",
        "SecurityLevel": "2"
    },
    {
        "EntityName": "All",
        "FileDownloadType": "2",
        "TypeOfData": "3",
        "Frequency": "1",
        "SecurityLevel": "2"
    }
]

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 nedenstående tabel.

Eksempel på udfyldelse ses i følgende tabel.

[
  {
    "Filename": "MatrikelGeometriGaeldendeDKComplete_GML_2022092",
    "SecurityLevel": "2",
    "FileFormat": "JSON"
  },
  {
    "Filename": "DAGI10MULTIGEOMHIST",
    "SecurityLevel": "1",
    "FileFormat": "GML"
  }
]

Bilag: Automated_Geographical_Filedownloads

Bilaget Automated Geographical Filedownloads kan benyttes af registeret til at definere hvilke entiteter som har geografiske felter som skal bruges til filtrering af fildownloads. Dette inkluderer at specificere navnet på entiteten og en liste af navne på de geografiske felter. Hvis en eller flere entiteter ikke har et eller flere geografiske felter behøves de ikke fremgå i bilaget.

JSON-skemaet Automated_Geographical_Filedownloads_Schema.json består af en liste af Automated_Geographical_Filedownloads objekter. Disse objekter består af følgende egenskaber:

GeographicFieldNames er en liste af unikke tekststrenge som indeholder navnene på de felter som fortæller geografisk om hvor data’en til entiteten befinder sig eller hører til. Her er det vigtigt at understrege at feltet skal være af samme type og det derfor ikke er muligt at blande geografiske felter af forskellige typer eller at lave et nyt objekt for samme entitet.

Som et eksempel kan man have godt have en entitet ”NavngivenVej” med kun ”administreresAfKommune” i listen eller med både “vejnavnebeliggenhed_vejnavnelinje”, “vejnavnebeliggenhed_vejnavneområde” og “vejnavnebeliggenhed_vejtilslutningspunkter”, men ikke alle fire i samme liste. Årsagen er at feltet “administreresAfKommune” er af typen ”Kommunekode” og ”vejnavnebeliggenhed” felterne er af typen ”string”. Disse egenskaber er alle krævede før JSON-filen kan valideres.

Bilag Automated_Wfs.json

Automated_Wfs_Schema.json bruges af et register, når de ønsker at definere hvilke entiteter de vil udstille via WFS for en given replikeringskanal. Bilaget angiver navnene på entiteterne.

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, det vil sige 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 nedenstående tabel.

Eksempel på udfyldelse ses i følgende tabel.

[
  {
    "Filename": "DHM2015_terraen",
    "SecurityLevel": "1",
    "FileFormat": "GeoTIFF"
  }
]

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å

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. Når ændringen træder i kraft, vil der blive lavet en ændring i både den interne og eksterne version.

Intern versionering

To replikeringskanaler

Én replikeringskanal

Valg af intern versionerings-fremgangsmåde

Datafordeleroperatøren og registrene bør i samarbejde vælge hvilken af de 2 mulige fremgangsmåder for intern versionering som registeret skal anvende. Det bør overvejes før processen om et skift sker, da implementeringen af den parallelle replikering-implementering i registerets eget system vil være stærkt afhængigt af hvilken fremgangsmåde der anvendes.

Det anbefales at hvis et register laver en mindre datamodel-ændring (som potentielt indeholder breaking changes) som leveres af samme bagvedliggende register-system at metoden fra Én replikeringskanal vælges. Dette kunne være tilføjelse af et par nye tabeller, fjernelse af enkelte felter, og lign.

Hvis registerets datamodel-ændring er en stor fuldamental ændring, som potentielt leveres af et helt separat ny-udviklet system der parallel-driftes med registerets gamle system, så anbefales det at metoden fra To replikeringskanaler vælges. Dette anbefales da denne metode ikke kræver nogen koordinering mellem registeret systemer, da hvert system har sin egen kanal med dedikeret sekvensnummer.

Da virkelighedens register datamodel-ændringer forventes at ligge et sted imellem de ovennævnte ender af skalaen, og da registeret muligvis har andre heri-ikke-beskrevne behov til paralleldriften, anbefales det at Datafordeleroperatøren og registrene sammen vurderer på en case-by-case basis hvilken fremgangsmåde der passer bedst til den konkrete situation.

Ekstern versionering

Samlet overblik

Hvis et register sender data til to separate replikeringskanaler, vil det totale flow se ud som i nedenstående figur.

Komplet flow for versionering ved to anvendelse af to replikeringskanaler

Hvis et register sender data til én enkelt replikeringskanal, vil det komplette flow se ud som neden for.

Som kan ses i ovenstående figurer så er den anvender-vendte eksterne snitflade altid ens overfor anvenderne, uagtet hvilken fremgangsmåde der er blevet valgt i den interne versionering.

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.

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.

Skema for generering af service til distribuering og fildownload

XMI og XSD placeres under den tilhørende replikeringskanals mappe i GitHub, medmindre ændringerne kommer i forbindelse med en ny replikeringskanal, så oprettes der en ny mappe i GitHub. Reglerne for As-is og To-be mapping håndteres af autogeneratoren og kræver ikke yderligere handlinger af registret.

Oprettelse af ny replikeringskanal

1. Aflever DLS i Github jf. Proces for aflevering i GitHub.
2. Netcompany Forvaltning opretter ny replikeringskanal eksisterende proces.

Versionering af Relations.json

Bilaget Relations versioneres på to niveauer:

1. Bilagsniveau. Selve bilaget har en version, som er identisk med datamodelversionen (dvs. DLS-versionen eller Git-versionen).
2. Inden for bilaget. I bilaget kan der specificeres flere relationsversioner (RelationVersions). Dette muliggør, at de fleksible GraphQL-tjenester kan understøtte paralleldrift af forskellige versioner af relationsdefinitionerne. En ny RelationVersion skal oprettes, når et register ønsker at opdatere de relationer, de udstiller via FO, på en sådan måde, at det medfører en ”breaking change”. Et eksempel på dette er givet i eksemplet neden for, hvor en relation (Husnummer-Bygning) er fjernet fra version 2 ift. version 1.

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.