Publiser til Felles Begrepskatalog

Beskrivelse

Denne rettleiinga viser korleis begrepsdefinisjonar i src/linkml/begrepskatalog/<katalog>/data/ vert konvertert til SKOS/Turtle og tilrettelagt for automatisk høsting til Felles Begrepskatalog.

Repoet publiserer SKOS/Turtle-filer til GitHub Pages som eit høstingsendepunkt. Felles Begrepskatalog kan konfigurere seg til å høste frå dette endepunktet, men repoet pusher ikkje direkte til data.norge.no — det følgjer "pull, ikkje push"-prinsippet.

Oversikt

flowchart LR
    A["src/linkml/begrepskatalog/\n<organisasjon>-begrepskatalog/data/.../\n<organisasjon>-begrepskatalog.yaml"] -->|make convert-data| B["generated/.../\n<organisasjon>-begrepskatalog.ttl"]
    B -->|GitHub Pages| C["brreg.github.io/\n.../<organisasjon>-begrepskatalog.ttl"]
    C -->|Automatisk høsting| D["data.norge.no/\nconcepts"]

Repoet skil mellom to typar YAML-filer:

Katalog	Føremål	Publiserast?
`src/linkml/<domain>/<modell>/examples/`	Illustrative døme — viser gyldig datafil, nyttast i gen-doc	Nei
`src/linkml/<domain>/<modell>/data/`	Reelle produksjonsdata — det som vert publisert	Ja

Eksempelfiler skal aldri sendast til Felles Begrepskatalog. Berre filer under data/ vert konverterte og publiserte.

<organisasjon> er ein generisk plasshaldar gjennom heile denne rettleiinga — for eit fullstendig, verkeleg eksempel, sjå src/linkml/begrepskatalog/brreg-begrepskatalog/.

Slik fungerer det

Lokal redigering: Du redigerer begrep i data/<katalog>/<katalog>.yaml
Generering: make convert-data konverterer YAML til SKOS/Turtle
Publisering til GitHub Pages: CI publiserer .ttl-filen til https://brreg.github.io/linkml-datamodellering-no/...
Høsting (ekstern prosess): Felles Begrepskatalog kan konfigurere seg til å høste frå GitHub Pages-adressa

Status i PoC-fasen: Steg 1-3 er implementerte. Steg 4 (faktisk høsting til Felles Begrepskatalog) må manuelt settas opp i Felles Begrepskatalog for kvar organisasjon som skal publisere sine begrepskataloger.

Føresetnader

make check-prereqs
make mcp-val-build   # byggjer mcp-linkml-validator (trengst for validering)

Dagleg arbeidsflyt — redigere begrep

Når du redigerer eksisterande begrep i src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/data/<organisasjon>-begrepskatalog/<organisasjon>-begrepskatalog.yaml:

1. Opprett ny git branch for endringa

2. Gjer endringa i datafila:

# src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/data/<organisasjon>-begrepskatalog/<organisasjon>-begrepskatalog.yaml
begrep:
  - id: https://begrep.<organisasjon>.no/<slug>
    anbefalt_term:
      - <norsk term>
    ...

3. Valider skjema og datafil i eitt steg:

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

Alle feil (severity: error) må rettast. Åtvaringar (warning) bør rettast, men blokkerer ikkje publisering.

4. Lag pullrequest til main:

CI-pipelinen køyrer same validering automatisk og publiserer ny .ttl-fil til GitHub Pages. Felles Begrepskatalog høstar oppdateringa ved neste syklus.

Kva policyen sjekkar

felles-begrepskatalog-policyen validerer at:

Skjemaet importerer SKOS-AP-NO-Begrep
Begrep-klassen har alle obligatoriske felt (skos:prefLabel, dct:identifier, dct:publisher, dcat:contactPoint, definisjon)
Samling-klassen har alle obligatoriske felt
dct:publisher-verdien er ein gyldig data.norge.no/organizations/<orgnr>-URI

Legg til eit nytt begrep

1. Opprett ny git branch for endringa

2. Vel ein stabil slug — sluggen vert del av ein permanent URI. Val av slug er uforanderleg etter første publisering.

3. Legg til i src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/data/<organisasjon>-begrepskatalog/<organisasjon>-begrepskatalog.yaml:

begrep:
  - id: https://begrep.<organisasjon>.no/<slug>
    anbefalt_term:
      - <norsk term>
    har_definisjon:
      - https://begrep.<organisasjon>.no/def/<slug>-nb
    identifikator_literal: "https://begrep.<organisasjon>.no/<slug>"
    kontaktpunkt_vcard:
      - https://begrep.<organisasjon>.no/kontakt/begrepsansvarleg
    utgjevar: https://data.norge.no/organizations/<orgnr>
    fagomrade:
      - https://psi.norge.no/los/tema/<los-tema>

definisjoner:
  - id: https://begrep.<organisasjon>.no/def/<slug>-nb
    tekst: <definisjonsteikst på bokmål>
    kjelde_relasjon: https://data.norge.no/vocabulary/relationship-with-source-type#self-composed

4. Valider:

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

5. Lag pullrequest til main og vent på publisering.

6. Etter stadfesta publisering i Felles Begrepskatalog — legg til URI-en i lock-fila:

echo "https://begrep.<organisasjon>.no/<slug>" >> \
  src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/published-uris.lock

URI-stabilitet

Kvart begrep har ein permanent URI (id:-feltet). Denne URI-en vert generert frå id: og lagt inn i den publiserte .ttl-fila som dct:identifier. Når Felles Begrepskatalog høstar, knyter han metadataa til URI-en.

URI-ar er permanente etter første publisering

Viss ein URI vert endra etter publisering, vil Felles Begrepskatalog:

Opprette eit nytt begrep med ny URI
Behalde det gamle begrepet med gamal URI som ein separat oppføring

Resultatet er duplikat i katalogen og øydelagde lenkjer.

URI-registeret (`published-uris.lock`)

src/linkml/begrepskatalog/<organisasjon>-begrepskatalog/published-uris.lock sporar alle publiserte URI-ar:

# Publiserte URI-ar for <organisasjon>-begrepskatalog — IKKJE endre eller slett eksisterande linjer.
# Nye URI-ar leggast til nedst etter publisering.
https://begrep.<organisasjon>.no/<slug-1>
https://begrep.<organisasjon>.no/<slug-2>

CI-pipelinen feilar ein PR dersom ei URI i lock-fila manglar frå datafila — dette fangar opp utilsikta sletting av publiserte begrep.

Deprekere eit begrep

Dersom eit begrep faktisk må erstattast (feil namn, omdefiniering):

Behald det opphavlege begrepet i datafila — slett det ikkje
Legg til er_erstatta_av: <ny-uri> på det gamle begrepet
Legg til erstattar: <gamal-uri> på det nye begrepet
Vurder euvoc_status: deprecated på det gamle begrepet

Registrering av høstingsendepunkt (éin gong)

Registrering krev ID-porten-innlogging og Altinn-rolle for organisasjonen.

Steg 1 — Logg inn på registrering.fellesdatakatalog.digdir.no med ID-porten (sikkerheitsnivå 3) og verifiser at organisasjonen di er synleg.

Nødvendig Altinn-rolle: sjå data.norge.no/nb/docs/sharing-data/login-and-access

Steg 2 — Navigér til admin.fellesdatakatalog.digdir.no/data-sources og legg til ny datakjelde:

Felt	Verdi
Utgjevar	Din organisasjon
Katalogtype	Begreper
Datakildentype	SKOS-AP-NO
Format	Turtle
Datakjelde-URL	`https://brreg.github.io/linkml-datamodellering-no/begrepskatalog/<organisasjon>-begrepskatalog/<organisasjon>-begrepskatalog.ttl`
Autentisering	(tomt — endepunktet er offentleg)

Steg 3 — Klikk «Høst» for umiddelbar høsting utan å vente på neste automatiske syklus. Behandlingstida er typisk nokre minutt.

Steg 4 — Verifiser på data.norge.no/concepts at begrepene visast med rett definisjon, utgjevar og kontaktpunkt.

CI-pipeline

Følgjande køyrer automatisk ved push til main når src/linkml/begrepskatalog/** er endra:

Jobb	Steg	Resultat ved feil
`validate`	`domain-validate-data`	Feiler viss datafila bryt `felles-begrepskatalog`-policyen
`validate`	`check-published-uris`	Feiler viss ei URI i lock-fila manglar frå datafila
`generate`	`domain-gen-data`	Publiserer ny `.ttl` til GitHub Pages

Lokalt tilsvarar dette:

# Validering (same som CI):
make domain-validate-data DOMAIN=begrepskatalog
make check-published-uris

# Konvertering:
make convert-data

Sett opp publisering for ny organisasjon

For å bruke same mønster for ein annan begrepskatalog:

1. Lag skjema etter ny-begrepsmodell.md.

2. Set validation_policy i build.yaml:

generators:
  ...
  example_rdf: true
validation_policy: felles-begrepskatalog

3. Lag src/linkml/begrepskatalog/<katalognavn>/data/<katalognavn>/<katalognavn>.yaml med produksjonsdata. Bruk det verkelege eksempelet src/linkml/begrepskatalog/brreg-begrepskatalog/data/brreg-begrepskatalog/brreg-begrepskatalog.yaml som mal.

4. Lag ei tom lock-fil:

cat > src/linkml/begrepskatalog/<katalognavn>/published-uris.lock << 'EOF'
# Publiserte URI-ar for <katalognavn> — IKKJE endre eller slett eksisterande linjer.
# Nye URI-ar leggast til nedst etter publisering.
EOF

5. Valider og push:

make mcp-linkml-valider-modell \
  SCHEMA=src/linkml/begrepskatalog/<katalognavn>/<katalognavn>-schema.yaml \
  POLICY=felles-begrepskatalog \
  INSTANCE=src/linkml/begrepskatalog/<katalognavn>/data/<katalognavn>/<katalognavn>.yaml

6. Registrer høstingsendepunktet (sjå §Registrering av høstingsendepunkt).

7. Legg til publiserte URI-ar i lock-fila etter stadfesta publisering.

Dokumenter publiseringa i portalen

Når begrepskatalogen er publisert og URI-ane er lagde inn i published-uris.lock, oppdaterer portalen seg automatisk neste gong make docs-publish køyrer.

publish.sh les published-uris.lock og legg automatisk til:

Ein informasjonsboks øvst på skjema-sida med høstingsendepunktet
Ei «Publisert til»-kolonne i domene-oversikta som lenkar til data.norge.no/concepts

Det er ingen manuell dokumentasjonsoppdatering nødvendig — det held å halde lock-fila oppdatert. For å sjå resultatet lokalt:

make docs-publish && make docs-serve

Kjende avgrensingar

Denne rettleiinga dekkjer publisering av begrepskatalogar til Felles Begrepskatalog. Følgjande avgrensingar gjeld i PoC-fasen:

Høsting

Automatisk høsting frå Felles Begrepskatalog er ikkje aktivt enno — repoet publiserer TTL-filer til GitHub Pages, men faktisk høsting må settast opp manuelt i Felles Begrepskatalog av den enkelte organisasjon som skal publisere sine begrepskataloger.
Ingen automatisk validering av at høstingsendepunktet faktisk er tilgjengeleg frå data.norge.no

URI-stabilitet

published-uris.lock sikrar stabile URI-ar, men mekanisme for å trekke tilbake feil-publiserte begrep er ikkje dokumentert
Endring av id-felt i eksisterande begrep vert ikkje automatisk oppdaga og varsla

Validering

felles-begrepskatalog-policy validerer metadata, men validerer ikkje at anbefalt_term er eit gyldigt norsk ord
Ingen automatisk sjekk for duplikate begrep på tvers av katalogar

Fullstendig oversikt: Sjå specs/bugs/README.md for komplett liste over kjende bugs og workarounds.

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

Sjå òg

Ny begrepskatalog — opprette nytt skjema
felles-begrepskatalog.yaml — full policy-definisjon
specs/publisering-felles-begrepskatalog.md — teknisk spesifikasjon
SKOS-AP-NO-Begrep-spesifikasjonen
Dele data — data.norge.no

Publiser til Felles Begrepskatalog

Oversikt

Slik fungerer det

Føresetnader

Dagleg arbeidsflyt — redigere begrep

Legg til eit nytt begrep

URI-stabilitet

URI-registeret (published-uris.lock)

Deprekere eit begrep

Registrering av høstingsendepunkt (éin gong)

CI-pipeline

Sett opp publisering for ny organisasjon

Dokumenter publiseringa i portalen

Kjende avgrensingar

Høsting

URI-stabilitet

Validering

Sjå òg

URI-registeret (`published-uris.lock`)