Gå til innhold

Publiser til Felles Datakatalog

Beskrivelse

Denne rettleiinga viser korleis informasjonsmodellar frå dette repoet vert skildra i ModelDCAT-AP-NO-format og tilrettelagt for automatisk høsting til Felles Datakatalog via GitHub Pages.

Repoet genererer ModelDCAT-AP-NO-metadata og publiserer dette til GitHub Pages som eit høstingsendepunkt. Felles Datakatalog 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/modellkatalog/<organisasjon>-modellkatalog/\ndata/<organisasjon>-modellkatalog/\n<organisasjon>-modellkatalog.yaml"] -->|make convert-data| B["generated/modellkatalog/\n<organisasjon>-modellkatalog/\n<organisasjon>-modellkatalog.ttl"]
    B -->|GitHub Pages| C["brreg.github.io/\n.../<organisasjon>-modellkatalog.ttl"]
    C -->|Automatisk høsting| D["data.norge.no/\nmodels"]

Katalogfila (src/linkml/modellkatalog/<organisasjon>-modellkatalog/data/<organisasjon>-modellkatalog/<organisasjon>-modellkatalog.yaml) er eit register over dei publiserte informasjonsmodellane og vert konvertert til Turtle ved hjelp av <organisasjon>-modellkatalog-schema.yaml som importerer ModelDCAT-AP-NO.

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

Slik fungerer det

  1. Modellering: Du lagar eller oppdaterer LinkML-skjemaer i src/linkml/<domain>/<modell>/
  2. Generering: make <domain> genererer ModelDCAT-AP-NO-metadata frå skjema-annotasjonar
  3. Publisering til GitHub Pages: CI publiserer metadata til https://brreg.github.io/linkml-datamodellering-no/...
  4. Høsting (ekstern prosess): Felles Datakatalog 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 Datakatalog) må koordinerast med Digitaliseringsdirektoratet for kvar organisasjon som skal publisere sine informasjonsmodellar.

Føresetnader

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

Dagleg arbeidsflyt — oppdatere katalogen

Når du redigerer eksisterande oppføringer i src/linkml/modellkatalog/<organisasjon>-modellkatalog/data/<organisasjon>-modellkatalog/<organisasjon>-modellkatalog.yaml:

1. Opprett ny git branch for endringa

2. Gjer endringa i katalogfila:

informasjonsmodellar:
  - id: https://<organisasjon>.no/modellkatalogar/<organisasjon>-modellkatalog/<slug>
    tittel:
      - "@value": "<norsk tittel>"
        "@language": "nb"
    ...

3. Valider skjema og katalogfil:

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

4. Lag pullrequest til main:

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

Kva policyen sjekkar

felles-datakatalog-policyen validerer at:

  • Skjemaet importerer ModelDCAT-AP-NO
  • Modellkatalog har alle obligatoriske felt (dct:title, dct:description, dct:identifier, dct:publisher, dcat:contactPoint, dct:hasPart)
  • Informasjonsmodell har alle obligatoriske felt
  • dct:publisher-verdien er ein gyldig data.norge.no/organizations/<orgnr>-URI

Legg til ein ny informasjonsmodell

1. Opprett ny git branch for endringa

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

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

informasjonsmodellar:
  - id: https://<organisasjon>.no/modellkatalogar/<organisasjon>-modellkatalog/<slug>
    tittel:
      - "@value": "<norsk tittel>"
        "@language": "nb"
    beskrivelse:
      - "@value": "<beskriving>"
        "@language": "nb"
    utgiver: https://data.norge.no/organizations/<orgnr>
    identifikator_literal: "https://<organisasjon>.no/modellkatalogar/<organisasjon>-modellkatalog/<slug>"
    informasjonsmodellidentifikator: "https://brreg.github.io/linkml-datamodellering-no/<domain>/<skjema>/"
    kontaktpunkt:
      - https://<organisasjon>.no/kontakt/modellforvaltning
    tema:
      - https://psi.norge.no/los/tema/<los-tema>
    lisens: http://publications.europa.eu/resource/authority/licence/CC_BY_4_0

4. Legg til URI-en i har_del: og modell:-lista på Modellkatalog-oppføringa.

5. Valider og lag pullrequest til main.

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

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

URI-stabilitet

Kvar Informasjonsmodell og Modellkatalog har ein permanent URI (id:-feltet).

URI-ar er permanente etter første publisering

Viss ein URI vert endra etter publisering, vil Felles Datakatalog opprette ein ny oppføring og behalde den gamle som ein separat post — duplikat og øydelagde lenkjer vert resultatet.

URI-registeret (published-uris.lock)

src/linkml/modellkatalog/<organisasjon>-modellkatalog/published-uris.lock sporar alle publiserte URI-ar. CI-pipelinen feilar ein PR dersom ei URI i lock-fila manglar frå katalogfila.

Registrering av høstingsendepunkt (éin gong)

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

Steg 1 — Logg inn på data.norge.no/publishing med ID-porten og verifiser at Din organisasjon er synleg.

Steg 2 — Legg til ny datakjelde:

Felt Verdi
Utgjevar Din organisasjon ()
Katalogtype Informasjonsmodellar
Datakildentype ModelDCAT-AP-NO
Format Turtle
Datakjelde-URL https://brreg.github.io/linkml-datamodellering-no/modell/<organisasjon>-modellkatalog/<organisasjon>-modellkatalog-eksempel.ttl
Autentisering (tomt — endepunktet er offentleg)

Steg 3 — Klikk «Høst» for umiddelbar høsting. Verifiser på data.norge.no/models at modellane viser seg med riktig utgjevar, tittel og LOS-tema.

CI-pipeline

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

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

Lokalt:

# Validering:
make domain-validate-data DOMAIN=modellkatalog
make check-published-uris

# Konvertering og forhåndsvis:
make modell && make docs-publish && make docs-serve

Dokumenter publiseringa i portalen

Når ei ny informasjonsmodell er publisert og URI-en er lagd inn i published-uris.lock, køyr:

make docs-publish

publish.sh les lock-fila og legg automatisk til informasjonsboks og «Publisert til»-kolonne i den genererte skjema-sida i portalen.

Sjå òg