Rettleiing: ny domenemodell

Arbeidsflyt

0 — Sjekk føresetnader og bygg images (éin gong)

make check-prereqs
make linkml-build-docker && make python-build-docker && make mcp-val-build

1a. — Scaffold

make new-model NAME=<modell> DOMAIN=<domain>

Dette oppretter:

src/linkml/<domain>/<modell>/
├── <modell>-schema.yaml       ← hovudskjema med stub-klasse og containerklasse
├── manifest.yaml              ← publiserings- og generatorkonfig
├── description.md             ← valfri beskrivelse av modellen, injiserast i portal-index etter ER-diagrammet
└── examples/
    └── <modell>-eksempel.yaml ← eksempelfil med minimal instans

Skjemaet passerer POLICY=bronze utan manuell redigering.

1b. (om ønskjeleg) Generer frå eksisterande JSON Schema

Legg JSON Schema-filen i tmp/, t.d. tmp/modell.json

make mcp-generate SCHEMA=tmp/modell.json
# Silver-annotasjonar (utgiver, endringsdato, status) automatisk:
make mcp-generate SCHEMA=tmp/modell.json PROFILE=silver

→ genererer tmp/modell-schema.yaml. Kopier til src/linkml/<domain>/<modell>/<modell>-schema.yaml

2 — Rediger skjemaet

Sjå Referanseskjema for eksempel på gyldig skjema med forklaringer.

Opne src/linkml/<domain>/<modell>/<modell>-schema.yaml og legg til klasser, slots og importar. Sjå Importhierarki og Kva importerer du? nedanfor.

3 — Valider undervegs

For hurtig validering kan du linte skjemaet: make lint SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml

Lint + validering mot medaljong-profil:

make mcp-validate SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml POLICY=bronze
make mcp-validate SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml POLICY=silver
make mcp-validate SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml POLICY=gold

Policy	Sjekkar
`bronze`	`id`, `name`, `title` (error); `default_prefix` (https-URI, error); `description`, `version`, `license` (warning); PascalCase-klasser, snake_case-slots, `class_uri`, `slot_uri`, `begrepsidentifikator` (warning)
`silver`	Bronze + `annotations.utgiver`, `annotations.endringsdato`, `annotations.status` (warning) + DCAT-AP-NO/DQV-AP-NO strukturkrav (error)
`gold`	Silver + FAIR F1–R1.3: full semantisk interoperabilitet

Sjå Valideringsreglar for fullstendig oversikt over kva som vert sjekka på kvart nivå.

4 — Full testsuite

Lint + validering + alle generatorar for eitt skjema. Utan SCHEMA= køyrer testsuiten for alle skjema.

make test SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml

Importhierarki

linkml:types          (alltid)
    ↓
common-ap-no          (berre AP-NO-profilane importerer denne direkte)
    ↓
dcat-ap-no / dqv-ap-no / skos-ap-no / …   (AP-NO-profiler)
    ↓
domenemodell          (importerer éin eller fleire AP-NO-profiler)

fint-common           (berre FINT-domenemodellane importerer denne)
    ↓
fint-administrasjon / fint-arkiv / …

fair-metadata         (kan importerast av alle domenemodeller)

Domenemodeller importerer AP-NO-profilane — ikkje common-ap-no direkte. Dei arvar typar, subsets og slots frå AP-NO automatisk gjennom profilane.

Kva importerer du?

Du lagar …	Importer
Ein AP-NO-profil	`linkml:types` + `../common/common-ap-no-schema`
Ein domenemodell (NGR, o.l.)	`linkml:types` + aktuelle AP-NO-profil(ar)
Ein FINT-domenemodell	`linkml:types` + `../fint-common/fint-common-schema`
Modell med FAIR-metadata	`linkml:types` + `../../fair/fair-metadata/fair-metadata-schema`

Kva får du frå AP-NO-profilane

Ved å importere ein AP-NO-profil arvar du automatisk alt frå common-ap-no — du treng ikkje importere common-ap-no direkte.

Typar frå common-ap-no

Namn	RDF-type	Bruk
`LangString`	`rdf:langString`	Fleirspråklege strenger (tittel, skildring …)
`Duration`	`xsd:duration`	Varigheit, t.d. `PT15M`
`GYear`	`xsd:gYear`	Årstal, t.d. `2024`
`NonNegativeInteger`	`xsd:nonNegativeInteger`	Telling, storleik

Gjenbrukbare slots (døme)

classes:
  MittObjekt:
    slots:
      - id          # identifier: true, range: uriorcurie
      - tittel      # slot_uri: dct:title, range: LangString
      - beskrivelse # slot_uri: dct:description, range: LangString
      - utgiver     # slot_uri: dct:publisher, range: uriorcurie
      - lisens      # slot_uri: dct:license, range: uriorcurie

Sjå src/linkml/ap-no/common/common-ap-no-schema.yaml for full liste.

FAIR-konformitet med fair-metadata

For å dokumentere at ein ressurs er FAIR-konform, importer fair-metadata:

imports:
  - linkml:types
  - ../../ap-no/dcat-ap-no/dcat-ap-no-schema
  - ../../fair/fair-metadata/fair-metadata-schema

Valider mot gold-policy (gold-policy validerer spesifikt FAIR konformitet):

make mcp-validate SCHEMA=src/linkml/<domain>/<modell>/<modell>-schema.yaml POLICY=gold

Genererte artefakter

Sjå Genererte artefakter i README for full oversikt over kva som vert generert per skjema.

Tilpass manifest for generering og publisering

Kvar modell har ei manifest.yaml ved sida av skjemafila som styrer kva artefaktar som vert genererte. make new-model oppretter standardkonfigen automatisk — alle generatorar på, ingen ekstra flagg.

For å slå av ein generator eller leggje til flagg, rediger manifest.yaml og køyr:

make config.mk   # regenerer Makefile-konfig frå alle manifest.yaml-filer

Sjå Modellmanifest for feltliste og eksempel per domenetype (standard, FINT, AP-NO/FAIR).

Referanseskjema

src/linkml/referanse/referanse-schema.yaml er eit annotert eksempelskjema som viser alle hovudmønster brukte i dette repoet: containerklasse, globale slots, import frå AP-NO-profil, class_uri/slot_uri, LangString og in_subset. Bruk det som oppslagsverk når du startar eit nytt skjema.

Modelleringsprinsipp

Norsk bokmål — alle klassenamn, slotnamn og skildringar skrivast på bokmål. Unntak: tekniske omgrep fastsett i ein spesifikasjon (t.d. dcat:Dataset → Datasett).

Slots, ikkje attributes — alle eigenskapar definerast som globale slots: på toppnivå, aldri som attributes: inne i ein klasse.

Lenking framfor inlining — klasser som kan opptre sjølvstendig får id-slot med identifier: true. Referansar til slike klasser skal ikkje ha inlined: true.

Eksplisitte URI-ar — alle klasser skal ha class_uri (unntatt tree_root-containerklassar). Alle slots skal ha slot_uri.

slot_usage for klassespesifikke innskrenkingar — required: true og in_subset: setjast i slot_usage på klassen, ikkje i den globale slotdefinisjonen.

Sjekkliste før innsjekking

[ ] id er ein HTTPS-URI
[ ] title og description er sett på skjemanivå
[ ] version er sett (t.d. "1.0.0")
[ ] default_prefix er ein absolutt HTTPS-URI med avsluttande /
[ ] Importerer AP-NO-profil(ar) — ikkje common-ap-no direkte
[ ] Klasse- og slotnamn er på norsk bokmål
[ ] Alle klasser (unntatt tree_root) har class_uri
[ ] Alle globale slots har slot_uri
[ ] make mcp-validate POLICY=bronze gir 0 feil
[ ] Om data_policy: silver eller høgare: annotations.utgiver, annotations.endringsdato,
    annotations.utgivelsesdato og annotations.status er fylt inn
[ ] make test køyrer utan feil