/
Den gode kodeliste

Den gode kodeliste

Arkitektur, governance og implementeringsmønster for kodelister i STAR City

1. Formål

Kodelister sikrer entydig og konsistent anvendelse af kodeværdier på tværs af forretningsdomæner, webservices og systemer i STAR City.

Denne side fastlægger obligatoriske regler for:

  • Ejerskab

  • Datamodel

  • Vedligehold

  • Runtime-validering

  • Tværgående genbrug

  • Eksponering via Komposit

  • Distribution via NuGet

Reglerne gælder for alle udviklingsteams i STAR City.

2. Arkitekturprincip

Kodelister følger nedenstående arkitekturmønster:

Lag 1 – Ejerskab

Én kodeliste ejes af ét forretningsdomæne.

Lag 2 – Distribution (intern genbrug)

Det ejende forretningsdomæne skal udstille kodelisten som en NuGet-pakke, indeholdende enums.

Lag 3 – Runtime-validering

Kodelisteværdier skal valideres ved write-operationer (POST/PUT) via Star.Foundation.

Lag 4 – Ekstern eksponering

Forretningsdomænet Komposit skal kunne udstille alle kodelister og kodelisteværdier på tværs af forretningsdomæner.

3. Ejerskab og governance

  • En kodeliste skal have ét entydigt ejer-forretningsdomæne.

  • Kun ejer-domænet må ændre kodelisten.

  • Andre forretningsdomæner skal anvende kodelisten via:

    • NuGet-pakken (intern kode)

    • Komposit (ekstern eksponering)

Komposit er et selvstændigt forretningsdomæne, der kan samle og eksponere information fra alle øvrige forretningsdomæner.

Det er et krav, at Komposit kan udstille samtlige kodelister og deres værdier.

4. Model for kodeliste

Følgende minimumsmodel er obligatorisk:

Element

Beskrivelse

Type

Min

Max

Element

Beskrivelse

Type

Min

Max

Identifier

Den entydige værdi, der identificerer kodeelementet og anvendes i services

int

–

–

Name

Kort, neutral tekstuel repræsentation af værdien

string

1

100

Description

Uddybende beskrivelse af værdien (fx lovgrundlag)

string

1

500

StartDate

Dato hvor værdien er gyldig fra

dateTime

–

–

EndDate

Dato hvor værdien ikke længere er gyldig

dateTime

–

–

IsActive

Angivelse af, hvorvidt kodelisteelement er aktivt og dermed kan benyttes ved oprettelse.

boolean

-

-

Regler

  • Identifier er unik inden for kodelisten.

  • Identifier må ikke genbruges – heller ikke efter udfasning.

  • Betydningen af en Identifier må aldrig ændres.

  • Name og Description skal være neutrale og må ikke indeholde UI- eller applikationsspecifik tekst.

  • StartDate og EndDate styrer gyldighed – ikke sletning.

  • Gyldighedsinterval er lukket/åben:

    • Gyldig fra og med StartDate

    • Gyldig til, men ikke med, EndDate

5. Vedligeholdelsesregler

Følgende regler er obligatoriske:

  • Koder må aldrig slettes.

  • Betydningen af en kode må aldrig ændres.

  • Ved ændret betydning:

    • eksisterende værdi markeres som udgået (EndDate sættes)

    • ny Identifier oprettes

  • Kodelister skal indeholde:

    • historiske værdier

    • aktuelle værdier

    • fremtidige værdier

  • Ændringer skal varsles.

Formålet er at sikre stabilitet og undgå breaking changes.

6. Distribution via NuGet (intern genbrug)

Hvert forretningsdomæne:

  • skal udstille sine kodelister som en NuGet-pakke

  • Pakken må kun indeholde enums

  • Andre forretningsdomæner skal anvende disse enums og må ikke redefinere egne kopier

Breaking changes

Breaking changes skal undgås.

Ved udfasning:

  • Enum-værdien bibeholdes

  • Den markeres som ikke længere gyldig (fx via attribut eller dokumentation)

  • Gyldighed styres via StartDate, EndDate samt flaget isActive i kodelisten – ikke ved fjernelse fra enum

Enums må ikke slettes.

7. Runtime-validering (Star.Foundation)

Kodelistevalidering skal ske ved write-operationer (POST/PUT).

Valideringen håndteres teknisk via Star.Foundation.

Den tekniske implementering er beskrevet her:
https://starwiki.atlassian.net/wiki/spaces/CITY/pages/1406926851/Star.Foundation+-+Teknisk+dokumentation#Kodelistevalidering

Formål:

  • Sikre at kun gyldige værdier kan registreres

  • Sikre at forretningsdato ligger inden for StartDate/EndDate

  • Undgå duplikeret valideringslogik i domænerne

Read-operationer validerer ikke.

8. Anvendelse af kodelister

Aftagere skal:

  • Cache kodelister lokalt

  • Opdatere dem dagligt

  • Kun anvende gyldige værdier ved registrering

Udgåede værdier:

  • Må fortsat forekomme i historiske data

  • Må anvendes ved historiske opdateringer

9. Sikkerhed

Princip

Kodelister indeholder udelukkende offentlige og ikke-følsomme reference-data.

Regler

  • Kodelister må ikke indeholde persondata eller fortrolige oplysninger.

  • Kodelister betragtes som offentlige data.

  • Kodelister skal kunne tilgås uden domænespecifik autorisation.

  • Ekstern adgang til kodelister skal ske via Komposit.

  • Kodelister må caches frit af aftagere.

Arkitekturimplikation

  • Kodelister må ikke kobles til borgerdata.

  • Autorisation må ikke være afhængig af rolle, sag eller CPR.

10. Anti-patterns (må ikke forekomme)

Følgende er ikke tilladt:

  • Kopiering af enums mellem domæner

  • Sletning af enum-værdier

  • Ændring af betydning på eksisterende Identifier

  • Egen valideringslogik fremfor Star.Foundation

  • Direkte eksponering af andres kodelister uden ejerskab

11. Samlet princip

En kodeliste i STAR City er:

  • Ejet ét sted

  • Distribueret via NuGet

  • Valideret via Star.Foundation

  • Eksponeret via Komposit

  • Versioneret uden breaking changes

  • Historisk komplet

  • Offentlig og uden følsomt indhold

Tilgængelighed: https://starwiki.atlassian.net/was