linkml-datamodellering-no

Proof of Concept

Dette repoet er ein Proof of Concept for LinkML-basert datamodellering i norsk offentleg sektor.

Kva det betyr:

Modellar og verktøy er under utvikling og kan endre seg
Dokumentasjonen kan vere ufullstendig eller utdatert
Nokre funksjonar er berre delvis implementerte
Det finst kjende avgrensingar og bugs
Ingen garantert stabilitet eller support-SLA

For eksterne organisasjonar: Les for bidragsytarar for forventningar til stabilitet og ansvar.

Målsetting

Dette repoet har som mål å realisere dei delane av Rammeverk for informasjonsforvaltning som går på begrepsmodellering, informasjonsmodellering, metadata og publisering til felles begrepskatalog og datakatalog i henhold til nasjonale veiledere og standarder. Det er tenkt som eit felles repo for nasjonale begreps- og datamodeller inkludert felles verktøy. Både modeller og verktøy kan benyttes lokalt i andre git-repoer.

Innhald

LinkML er eit open kjeldekode-modelleringsspråk der du skriv skjemaer i YAML som skildrar datastrukturen din, og som du kan nytte til å generere skjemaer, data, diagram og dokumentasjon i andre format (LinkML generators). Generatorane konverterer både til tradisjonelle format (JSON Schema, Python, Protobuf) og W3C-semantiske format (RDF/Turtle, OWL, SHACL, JSON-LD) utan behov for ekstra mapping.

Dette kodelageret inneheld:

LinkML-modellar for norske W3C-applikasjonsprofilar og offentlege domenemodellar for gjenbruk.
mcp-linkml-modell-utkast for å generere utkast til nye informasjonsmodellar i LinkML format ihht Rammeverk for informasjonsforvaltning.
mcp-linkml-begrep-utkast for å generere utkast til nye begreper i LinkML format ihht skos-ap-no standarden.
mcp-linkml-validator for å validere LinkML-skjemaer ihht Felles modelleringsregler for offentlig forvaltning og FAIR prinsippa. Validatoren implementerer kvalitets-profilar (bronze, silver, gold), publiserings-profilar (felles begrepskatalog og felles datakatalog) og har støtte for egendefinerte profilar.
LinkML-generatorar for å produsere artefakter i andre format frå LinkML-skjemaer.
Github Actions pipelines for å automatisk generere, validere og publisere artefakter frå LinkML-skjemaer.
Guide for å publisere begreper til felles begrepskatalog ihht skos-ap-no standarden.
Guide for å publisere informasjonsmodellar til felles datakatalog ihht modeldcat-ap-no standarden.
Github Pages dokumentasjonsportal med oversikt over alle LinkML-skjemaer og genererte artefakter med styling ihht designsystemet.no.
Opplegg for å bootstrappe eit eksternt repo for lokal LinkML modellering.

Avgrensingar

Repoet er i PoC-fase og har nokre kjende avgrensingar. Sjå desse dokumenta for fullstendig oversikt:

SCOPE.md — kva repoet er, kva det ikkje er, og kva som høyrer heime her
BUGS.md — komplett liste over kjende bugs og workarounds

Rapporter nye problem: Opne eit GitHub Issue med merkelappen bug.

Spørsmål og idear: Bruk GitHub Discussions for spørsmål, idear og erfaringsdeling — Issues er for bug-rapportar og konkrete endringsforslag.

Kom i gang

Her får du ei kjapp innføring i oppsett av lokalt miljø for å komme igang med datamodellering og begrepsarbeid.

Føresetnader: linux eller windows med WSL2, Git, Podman (rootless) og GNU make.

# Sjekk at alt er på plass
make check-prereqs

# Bygg container-images (éin gong)
make linkml-build-docker && make python-build-docker && make mcp-val-build && make mcp-mod-build && make mcp-begrep-build

Datamodellering

Bruk oppskrifta under for å komme igang med datamodellering.

Bytt ut domene og modellnavn med dine aktuelle navn.

# 1. Lag eit nytt tomt LinkML-skjema (skjema + filstruktur)
make new-modell NAME=modellnavn DOMAIN=domene

# 1b. (om ønskjeleg) Generer frå eksisterande JSON Schema
# Legg JSON Schema-filen i tmp/, t.d. tmp/modellnavn.json
make mcp-linkml-modell-utkast SCHEMA=tmp/modellnavn.json
# → genererer tmp/modellnavn-schema.yaml. Kopier til src/linkml/domain/modellnavn/

# 2. Rediger modellfila etter behov
#    → src/linkml/domain/modellnavn/modellnavn-schema.yaml

# 3. Valider skjema
make mcp-linkml-valider-modell \
  SCHEMA=src/linkml/domene/modellnavn/modellnavn-schema.yaml \
  POLICY=felles-datakatalog

# 4. (om ønskjeleg) angi kva artefakter som skal genereres og publiseres i build.yaml
# → src/linkml/domain/modellnavn/build.yaml

# 4b. Generer artefakter og publiser til dokumentasjonsportal
make <domain> && make docs-publish && make docs-serve   # → http://localhost:8000

Nye skjema under src/linkml/<domain>/<modellnavn>/ vert oppdaga automatisk.

For full rettleiing: sjå Ny domenemodell og Publiser til Felles Datakatalog.

Begrepsmodellering

Bruk oppskrifta under for å komme igang med begrepsmodellering.

Bytt ut domene, begrepssamling-namn og organisasjon med dine aktuelle namn.

# 1a. Opprett ny begrepssamling (filstruktur for begrep)
make new-begrepssamling DOMAIN=domene NAME=begrepssamling-namn

# 1b. (om ønskjeleg) Generer begrepsutkast frå eksisterande tekst
make mcp-linkml-begrep-utkast INPUT=<sti-til-tekstfil>
# → genererer begrepsutkast i tmp/ og kopier til src/linkml/domene/begrepssamling-namn/begrep/begrepnavn.yaml

# 2. Rediger begrep etter behov
#    → src/linkml/domene/begrepssamling-namn/begrep/<begrep-slug>.yaml

# 3. Aggreger til begrepskatalog
make gen-begrepskatalog-instance

# 4. Valider begrepskatalog
make mcp-linkml-valider-modell \
  SCHEMA=src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/<organisasjon>-begrepskatalog-schema.yaml \
  POLICY=felles-begrepskatalog

# 5a. (om ønskjeleg) angi kva artefakter som skal genereres fra begrepskatalogen i build.yaml
#    → src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/data/<organisasjon>-begrepskatalog/build.yaml

# 5b. Generer artefakter og publiser til dokumentasjonsportal
make begrepskatalog && make docs-publish && make docs-serve   # → http://localhost:8000

Nye begrepssamlingar under src/linkml/<domain>/<begrepssamling>/ vert oppdaga automatisk.

For full rettleiing: sjå Ny begrepskatalog og Publiser til Felles Begrepskatalog.

Sjå CLAUDE.md for modelleringsprinsipp og COMMANDS.md for alle tilgjengelege kommandoar.

Bruk frå eksternt repo

Vil du bruke AP-NO-profilene i ditt eige repo utan å jobbe inni dette monorepoet? Bootstrap-scriptet legg til dei to filene du treng på eitt minutt:

curl -sSL https://raw.githubusercontent.com/brreg/linkml-datamodellering-no/main/bootstrap.sh | bash

Importer deretter AP-NO-profilene direkte i skjemaet ditt via GitHub Raw-URL:

imports:
  - linkml:types
  - https://raw.githubusercontent.com/brreg/linkml-datamodellering-no/dcat-ap-no-v2.8.0/src/linkml/ap-no/dcat-ap-no/dcat-ap-no-schema

Validering og generering skjer via reusable GitHub Actions-workflows i dette repoet — ingen lokal installasjon er nødvendig. Sjå Bruk frå eksternt repo for full rettleiing.

Domener

Datamodellane er gruppert i domener.

Domena ligg under src/linkml/<domain>/

Domene	Skildring	Dokumentasjon
REFERANSE	Enkle eksempel på gyldige LinkML-modellar (referanseimplementasjonar)
FAIR	FAIR-metadataoverbygning — Findable, Accessible, Interoperable, Reusable. Kan importerast av alle domenemodellar.	FAIR principles
AP-NO	Norske W3C-applikasjonsprofilar — DCAT, SKOS, CPSV, DQV m.fl. Importerast av domenemodellar.	RDF-baserte maskinlesbare ressurser
NGR	Nasjonale grunndata — adresse, eigedom, person og verksemd.	Nasjonale grunndata
OREG	Offentlege register.
FINT	FINT felleskomponent — integrasjonsmodellar for fylkeskommunal sektor.	FINT informasjonsmodell
SAMT	SAMT — integrasjonsmodellar for kommunesektoren.	SAMT-prosjektet
BEGREPSKATALOG	Begrepskatalog etter SKOS-AP-NO-Begrep. Instansdatafiler vert automatisk konverterte til SKOS/RDF for publisering til Felles Begrepskatalog.	SKOS-AP-NO-Begrep
MODELLKATALOG	Modellkatalog for informasjonsmodellar etter ModelDCAT-AP-NO for publisering til Felles Datakatalog.	ModelDCAT-AP-NO

Skjema

Det er eit skjema i LinkML format for kvar datamodell.

Skjema ligg under src/linkml/<domain>/<skjema>/

Domene	Skjema	Skildring	Dokumentasjon
FAIR	fair-metadata	"FAIR-metadataoverbygning (FAIR-prinsippa)"	www.go-fair.org
AP-NO	common-ap-no	Felles slot-definisjonar for alle AP-NO-profilar
AP-NO	cpsv-ap-no	Offentlege tenester og hendingar	data.norge.no
AP-NO	dcat-ap-no	Datakatalogar og datasett	data.norge.no
AP-NO	dqv-ap-no	Datakvalitet	data.norge.no
AP-NO	modelldcat-ap-no	Informasjonsmodellar	data.norge.no
AP-NO	skos-ap-no	Omgrepsamlingar	data.norge.no
AP-NO	xkos-ap-no	Utvida klassifikasjon	data.norge.no
REFERANSE	referansemodell-bronze	Viser minstekrava for å bestå bronsepolicyen: HTTP(S)-id, schema-metadata (title, version), class_uri, identifier-slot, slot_uri og begrepsidentifikator på riktig format.
REFERANSE	referansemodell-gold	Viser minstekrava for å bestå gullpolicyen: alle sølv-krav pluss FAIR-metadata (title, version, prefiks, lisens, proveniens).
REFERANSE	referansemodell-silver	Viser minstekrava for å bestå sølvpolicyen: alle bronse-krav pluss DCAT-AP-NO og DQV-AP-NO-klassar med påkravde slots og containerklasse.
REFERANSE	referansemodell	Enkel eksempelmodell for å demonstrere gyldig LinkML-struktur
NGR	ngr-adresse	Adresse	informasjonsforvaltning.github.io
NGR	ngr-eiendom	Fast eigedom, matrikkeleining og bygning	informasjonsforvaltning.github.io
NGR	ngr-person	Person, identifikasjon og familierelasjonar	informasjonsforvaltning.github.io
NGR	ngr-virksomhet	Verksemder, roller og organisasjonsstruktur	informasjonsforvaltning.github.io
OREG	enhetsregisteret-bvrinn	Berettigede, verger, rettighetshavere i næring (BVRiNN)
OREG	lunchregisteret	Generert modell for 'lunchregisteret'.
OREG	register-over-aksjeeiere	Aksjeeigarar og eigedelar
FINT	fint-administrasjon	Lønn, arbeidsforhold, organisasjon	informasjonsmodell.felleskomponent.no
FINT	fint-arkiv	Sak, journal, dokument	informasjonsmodell.felleskomponent.no
FINT	fint-common	Felles klassar for FINT
FINT	fint-okonomi	Økonomi og rekneskap	informasjonsmodell.felleskomponent.no
FINT	fint-personvern	Personvernmeldingar	informasjonsmodell.felleskomponent.no
FINT	fint-ressurs	Ressursar	informasjonsmodell.felleskomponent.no
FINT	fint-utdanning	Utdanning og skule	informasjonsmodell.felleskomponent.no
SAMT	samt-bu	Skular og barnehagar	docs.samt-bu.no

AP-NO-profilane og FAIR-metadata er skjema utan tree_root — dei er ikkje sjølvstendige, men meinte å importerast av domenemodellar.

Genererte artefakter

Du kan generere artefakter fra LinkML skjemaet.

Genererte artefakter ligg under generated/<domain>/<skjema>/.
Køyr make <domain> for å generere alle artefakter for eit domene.
Kvar modell kan slå av einskilde generatorar via src/linkml/<domain>/<skjema>/build.yaml — sjå Generatorkonfigurasjon for detaljar.

Artefakt	Fil	Brukstilfelle	W3C semantisk	build.yaml flag	Generator
Modellmetadata ihht ModellDCAT-AP-NO	`metadata/<skjema>-manifest.yaml`	ModelDCAT-AP-NO metadata for publisering til Felles Datakatalog	✓	—	`gen-informasjonsmodell-instance`
JSON-LD kontekst	`<skjema>-context.jsonld`	Mapping frå JSON til RDF — brukast saman med API	✓	`jsonld_context`	`gen-jsonld-context`
SHACL shapes	`<skjema>-shapes.ttl`	Validering av RDF-data mot skjema i triple stores	✓	`shacl`	`gen-shacl`
OWL ontologi	`<skjema>-ontology.ttl`	Maskinlesbar ontologi for semantiske verktøy	✓	`owl`	`gen-owl`
RDF/Turtle skjema	`<skjema>-schema.ttl`	Fullstendig RDF-representasjon av skjemaet	✓	`rdf`	`gen-rdf`
Eksempel-RDF	`<skjema>-eksempel.ttl`	Konkret RDF-instans for testing og dokumentasjon	✓	`example_rdf`	`convert-rdf`
Python-klassar	`<skjema>-model.py`	Direkte bruk i Python-applikasjonar via LinkML	—	`python`	`gen-python`
JSON Schema	`<skjema>-schema.json`	Validering av JSON-data i applikasjonar og RESTful integrasjon	—	`json_schema`	`gen-jsonschema`
XSD-skjema	`<skjema>-schema.xsd`	XML Schema for XML-basert integrasjon	—	`xsd`	`gen-xsd`
Protobuf-skjema	`<skjema>-schema.proto`	gRPC og Protocol Buffers-integrasjon	—	`protobuf`	`gen-proto`
GraphQL-skjema	`<skjema>-schema.graphql`	Typedefinisjonar (SDL) for GraphQL-API	—	`graphql`	`gen-graphql`
AsyncAPI-spec	`<skjema>-asyncapi.yaml`	Asynkron meldingsutveksling (event-driven API)	—	`asyncapi`	`gen-asyncapi`
OpenAPI-spec	`<skjema>-openapi.yaml`	RESTful API-dokumentasjon (OpenAPI 3.1)	—	`openapi`	`gen-openapi`
ER-diagram	`<skjema>-erdiagram.md`	Visuell oversikt over klasser og relasjonar (Mermaid)	—	`erdiagram`	`gen-erdiagram`
Klasse-diagram	`diagrams/<skjema>.puml` + `.svg`	Klassediagram for presentasjon og dokumentasjon (PlantUML)	—	`plantuml`	`gen-plantuml`
HTML-dokumentasjon	`docs/`	Menneskelesleg referansedokumentasjon basert på markdown	—	`docs`	`gen-docs`
DQV-målingar	`dqv-measurements.ttl`	Datakvalitetsmålingar (kun datakatalog-modellar)	✓	—	`gen-dqv-measurements`
ModelDCAT-element	`modelldcat-elements.ttl`	Modellkatalog-element (kun modellkatalog-modellar)	✓	—	`gen-modelldcat-elements`

Publisering til eksterne system: Sjå Publiseringsflyt for oversikt over GitHub Pages-publisering og høsting til Felles Begrepskatalog/Datakatalog.

Genererte begrepskatalogar

Begrepskatalogar er automatisk genererte oversikter over begrep per organisasjon, basert på SKOS-AP-NO standarden.

Begrepskatalogar ligg under src/linkml/begrepskatalog/

Domene	Begrepskatalog	Organisasjon	Skildring	Generator
begrepskatalog	brreg-begrepskatalog	Registerenheten i Brønnøysund	Begrepskatalog for Registerenheten i Brønnøysund sine begrep	`gen-begrepskatalog-instance`

Genererte modellkatalogar

Modellkatalogar er automatisk genererte oversikter over informasjonsmodellar per organisasjon, basert på ModelDCAT-AP-NO standarden.

Modellkatalogar ligg under src/linkml/modellkatalog/

Domene	Modellkatalog	Organisasjon	Skildring	Generator
modellkatalog	brreg-modellkatalog	Brønnøysundregistra	Modellkatalog for Brønnøysundregistra sine informasjonsmodellar	`gen-modellkatalog-instance`
modellkatalog	digdir-modellkatalog	Digitaliseringsdirektoratet	Modellkatalog for Digitaliseringsdirektoratet sine informasjonsmodellar	`gen-modellkatalog-instance`
modellkatalog	kartverket-modellkatalog	Kartverket	Modellkatalog for Kartverket sine informasjonsmodellar	`gen-modellkatalog-instance`
modellkatalog	ksdigital-modellkatalog	KS Digital	Modellkatalog for KS Digital sine informasjonsmodellar	`gen-modellkatalog-instance`
modellkatalog	novari-modellkatalog	Novari IKS	Modellkatalog for Novari IKS sine informasjonsmodellar	`gen-modellkatalog-instance`
modellkatalog	skatteetaten-modellkatalog	Skatteetaten	Modellkatalog for Skatteetaten sine informasjonsmodellar	`gen-modellkatalog-instance`

Katalogstruktur

Her finn du oversikt over dei mest sentrale katalogane i repoet.

linkml-datamodellering-no/
├── src/
│   ├── assets/                                    # Containere, skript og malar
│   ├── linkml/                                    # Kilde for LinkML modeller (og begrepsinstanser)
│   │   └── <domain>/
│   │       └── <modell>/
│   │           ├── <modell>-schema.yaml           # Datamodel
│   │           ├── build.yaml                     # Byggkonfigurasjon
│   │           ├── published-uris.lock            # Stabile URI-er for publiserte katalogar
│   │           ├── examples/                      
│   │           │   └── <modell>-eksempel.yaml     # Eksempeldatafil
│   │           └── data/                          # Kildedata for publiserte katalogar
│   │               └── <datafil-katalog>/
│   │                   ├── <datafil-katalog>.yaml # Datafil for begrepskatalog
│   │                   └── build.yaml             # Datafil-byggkonfigurasjon
│   │
│   ├── mcp-linkml-validator/                      # MCP-server: policy-basert LinkML validering
│   ├── mcp-linkml-modell-utkast/                  # MCP-server: generering av LinkML modell-utkast
│   ├── mcp-linkml-begrep-utkast/                  # MCP-server: generering av LinkML begreps-utkast
│   └── tmp/                                       # Mellombelse filer, t.d. JSON Schema-filer til mcp-linkml-modell-utkast
│
├── bootstrap.sh                                   # Bootstrap-script for eksterne repo
├── bugs/                                          # Kjente bugs
├── tests/                                         # Testar og fixtures
├── generated/                                     # Genererte artefakter (ikkje sjekka inn i git)
├── make/                                          # GNU Make filer for make kommandoar. Sjå COMMANDS.md for kommandoar.
├── mkdocs/                                        # Dokumentasjonsportal (MkDocs Material)
│   └── docs/                                      # Den publiserte dokumentasjonsportalen
│       └── <domain>/
│          └── <modell>/
│               └── index.md                       # Hoveddokumentasjon for kvar datamodell (generert av publish.sh)
└── specs/
    ├── backlog/                                   # Planer for endringar og nye features
    ├── done/                                      # Utførte planer
    └── bugs/                                      # Kjente bugs

For bidragsytarar

Her finn du sentrale dokumenter for bidragsytere.

Dersom du skal bidra til repoet, les desse dokumenta:

PRINCIPLES.md — designprinsipp for modellering
CONVENTIONS.md — namnekonvensjonar, manifestformat og commit-meldingar
GOVERNANCE.md — roller, eigarskap og RFC-prosess
CONTRIBUTING.md — korleis bidra (PR-prosess, kodegjennomgang)
README-tabellgenerering — korleis README-tabellane vert genererte

Portalen vart sist bygd: 2026-08-15 08:57 CEST