linkml-datamodellering-no

NB dette er en Proof of Concept

Norske W3C-applikasjonsprofiler og offentlege domenemodeller i LinkML-format.

LinkML er eit open kjeldekode-modelleringsspråk der du skriv skjema i YAML som skildrar datastrukturen din, og som du kan nytte til å generere skjema, 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-applikasjonsprofiler og offentlege domenemodeller for gjenbruk.
mcp-linkml-modell-utkast, mcp-linkml-begrep-utkast og mcp-linkml-validator (mcp servere) for å generere og validere LinkML-skjema (med moglegheit for KI-integrasjon).
LinkML-generatorar for å produsere artefakter i andre format frå LinkML-skjema.
Github Actions pipelines for å automatisk generere, validere og publisere artefakter frå LinkML-skjema.
Github Pages dokumentasjonsportal med oversikt over alle LinkML-skjema og genererte artefakter.
Opplegg for å bootstrappe eit eksternt repo for lokal LinkML modellering.

Kom i gang

Føresetnader: Podman (rootless), WSL2 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

Bytt ut domene og modellnavn med dine aktuelle navn.

# 1. Lag eit nytt tomt LinkML-skjema (skjema + filstruktur)
make new-model 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-generate SCHEMA=tmp/modellnavn.json
# → genererer tmp/modellnavn-schema.yaml. Flytt ho til src/linkml/domain/modellnavn/

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

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

# 4. Generer artefakter og publiser til dokumentasjonsportal
make <domain> && make 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

Bytt ut katalognavn med ditt aktuelle navn.

# 1. Opprett ny begrepskatalog (skjema + filstruktur)
make new-model NAME=katalognavn DOMAIN=begrepskatalog

# 2. Rediger datafila med reelle begrep
#    → src/linkml/begrepskatalog/katalognavn/data/katalognavn/katalognavn.yaml

# 3. Valider skjema og datafil
make mcp-validate \
  SCHEMA=src/linkml/begrepskatalog/katalognavn/katalognavn-schema.yaml \
  POLICY=felles-begrepskatalog \
  INSTANCE=src/linkml/begrepskatalog/katalognavn/data/katalognavn/katalognavn.yaml

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

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

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/v1.0.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

Domene	Skildring	Dokumentasjon
fair	FAIR-metadataoverbygning — Findable, Accessible, Interoperable, Reusable. Kan importerast av alle domenemodeller.	FAIR principles
ap-no	Norske W3C-applikasjonsprofiler — DCAT, SKOS, CPSV, DQV m.fl. Importerast av domenemodeller.	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

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

Domene	Skjema	Skildring	Dokumentasjon
fair	fair-metadata	FAIR-metadataoverbygning (FAIR-prinsippa)	www.go-fair.org/fair-principles/
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/specification/cpsv-ap-no
ap-no	dcat-ap-no	Datakatalogar og datasett	data.norge.no/specification/dcat-ap-no
ap-no	dqv-ap-no	Datakvalitet	data.norge.no/specification/dqv-ap-no
ap-no	modelldcat-ap-no	Informasjonsmodellar	data.norge.no/specification/modelldcat-ap-no
ap-no	skos-ap-no	Omgrepsamlingar	data.norge.no/specification/skos-ap-no-begrep
ap-no	xkos-ap-no	Utvida klassifikasjon	data.norge.no/specification/xkos-ap-no
fint	fint-common	Felles klassar for FINT
fint	fint-administrasjon	Lønn, arbeidsforhold, organisasjon	informasjonsmodell.felleskomponent.no/docs/package_administrasjon?v=v4.0.20
fint	fint-arkiv	Sak, journal, dokument	informasjonsmodell.felleskomponent.no/docs/package_arkiv?v=v4.0.20
fint	fint-okonomi	Økonomi og rekneskap	informasjonsmodell.felleskomponent.no/docs/package_okonomi?v=v4.0.20
fint	fint-personvern	Personvernmeldingar	informasjonsmodell.felleskomponent.no/docs/package_personvern?v=v4.0.20
fint	fint-ressurs	Ressursar	informasjonsmodell.felleskomponent.no/docs/package_ressurs?v=v4.0.20
fint	fint-utdanning	Utdanning og skule	informasjonsmodell.felleskomponent.no/docs/package_utdanning?v=v4.0.20
ngr	ngr-adresse	Adresse	informasjonsforvaltning.github.io/nasjonale-grunndata/#Adresse
ngr	ngr-eiendom	Fast eigedom, matrikkeleining og bygning	informasjonsforvaltning.github.io/nasjonale-grunndata/#Temaomr%C3%A5deEiendom
ngr	ngr-person	Person, identifikasjon og familierelasjonar	informasjonsforvaltning.github.io/nasjonale-grunndata/#Person
ngr	ngr-virksomhet	Verksemder, roller og organisasjonsstruktur	informasjonsforvaltning.github.io/nasjonale-grunndata/#Virksomhet
oreg	register-over-aksjeeiere	Aksjeeigarar og eigedelar
samt	samt-bu	Skular og barnehagar	docs.samt-bu.no/om/

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

Genererte artefakter

Pull, ikkje push. Dette repoet genererer og publiserer artefaktar til GitHub Pages og GitHub Releases. Andre system hentar artefaktane derifrå sjølve — repoet pusher aldri artefaktar til eksterne kjelder. Å pushe til ekstern schema-registry, datakatalog eller anna API krev spesialtilpassingar per målsystem og knyt repoet til ekstern tilgjengelegheit og autentisering, noko som er utanfor dette repoets ansvarsfelt.

Køyr make <domain> for å generere alle artefakter for eit domene. Kvar generator produserer éin fil under generated/<domain>/<skjema>/. Kvar modell kan slå av einskilde generatorar via manifest.yaml — sjå Generatorkonfigurasjon for detaljar.

Artefakt	Fil	Brukstilfelle	W3C semantisk	manifest.yaml flag
JSON-LD kontekst	`<skjema>-context.jsonld`	Mapping frå JSON til RDF — brukast saman med API	✓	`jsonld_context`
SHACL shapes	`<skjema>-shapes.ttl`	Validering av RDF-data mot skjema i triple stores	✓	`shacl`
OWL ontologi	`<skjema>-ontology.ttl`	Maskinlesbar ontologi for semantiske verktøy	✓	`owl`
RDF/Turtle skjema	`<skjema>-schema.ttl`	Fullstendig RDF-representasjon av skjemaet	✓	`rdf`
Eksempel-RDF	`<skjema>-eksempel.ttl`	Konkret RDF-instans for testing og dokumentasjon	✓	`example_rdf`
Python-klassar	`<skjema>-model.py`	Direkte bruk i Python-applikasjonar via LinkML	—	`python`
JSON Schema	`<skjema>-schema.json`	Validering av JSON-data i applikasjonar og RESTful integrasjon	—	`json_schema`
Protobuf-skjema	`<skjema>-schema.proto`	gRPC og Protocol Buffers-integrasjon	—	`protobuf`
ER-diagram	`<skjema>-erdiagram.md`	Visuell oversikt over klasser og relasjonar (Mermaid)	—	`erdiagram`
HTML-dokumentasjon	`docs/`	Menneskelesleg referansedokumentasjon basert på markdown	—	`docs`
Klasse-diagram	`diagrams/<skjema>.puml` + `.svg`	Klassediagram for presentasjon og dokumentasjon (PlantUML)	—	`plantuml`

Katalogstruktur

linkml-datamodellering-no/
├── src/
│   ├── assets/                                    # Containere, skript og malar
│   ├── linkml/                                    # Kilde for LinkML modeller (og begrepsinstanser)
│   │   └── <domain>/
│   │       └── <modell>/
│   │           ├── <modell>-schema.yaml           # Datamodel
│   │           ├── manifest.yaml                  # Modell-manifest
│   │           ├── 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
│   │                   └── manifest.yaml          # Datafil-manifest
│   │
│   ├── 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
│
├── bootstrap.sh                                   # Bootstrap-script for eksterne repo
├── tests/                                         # Testar og fixtures
├── generated/                                     # Genererte artefakter (ikkje sjekka inn i git)
├── mkdocs/                                        # Dokumentasjonsportal (MkDocs Material)
│   └── docs/                                      # Den publiserte dokumentasjonsportalen
├── specs/
│   ├── backlog/                                   # Planer for endringar og nye features
│   ├── done/                                      # Utførte planer
│   └── bugs/                                      # Kjente bugs
└── tmp/                                           # Mellombelse filer, t.d. JSON Schema-filer til mcp-linkml-modell-utkast