FAQ og informasjon om valideringsregler for DCAT-AP-NO versjon 3

[terje.sylvarnes]

Forklaring av regler (SHACL Shapes) for DCAT-AP-NO v3

Introduksjon

Vi har nå publisert beta-versjon av valideringsregler for DCAT-AP-NO versjon 3! Reglene validerer beskrivelser av datasett og API-er, i RDF-formatet. Har du tilbakemeldinger så ta kontakt med oss på e-post eller legg inn et Issue på GitHub-siden til DCAT-AP-NO.

• Lenke til reglene: https://github.com/Informasjonsforvaltning/dcat-ap-no/tree/develop/shacl
• Lenke for å opprette nytt issue i GitHub: https://github.com/Informasjonsforvaltning/dcat-ap-no/issues/new/choose
• E-post: mailto:informasjonsforvaltning@digdir.no

De nye reglene er i filene dcatapno3-core-shapes.ttl, dcatapno3-range-shapes.ttl og dcatapno3-vocabulary-shapes.ttl.

Vi har fokusert på to bruksområder for reglene:

• 1. Datakataloger (som data.norge.no)
• 2. Datatilbydere som tilgjengeliggjør datasett- og API-beskrivelser

Vi har hatt som mål at reglene og feilmeldingene skal hjelpe datatilbyder å lage så gode beskrivelser som mulig. Om du opplever at dette ikke er tilfellet vil vi gjerne høre fra deg. F.eks. om feilmeldingene er uklare, ikke til hjelp, eller om de gir feil på noe du mener er en korrekt beskrivelse.

Hvorfor er det flere regelsett?

En målsetning er at feilmeldingene skal være forårsaket av noe datatilbyder har ansvar for og mulighet til å rette opp i. En del egenskaper peker til koder fra eksterne kodelister, for eksempel kodelister fra EUs Publications Office, og eventuelle feil i innholdet til disse kodene er ikke relevant for datatilbyder. På den andre siden beriker den nasjonale datakatalogen beskrivelsene med disse kodene, i tillegg til informasjon om virksomheter. Datakatalogen har dermed mer informasjon tilgjengelig på valideringstidspunktet, og skal kunne validere denne informasjonen. For å støtte opp om disse ulike bruksmønstrene tilbyr vi et hoved-regelsett som kan brukes av alle (dcatapno3-core-shapes.ttl), i tillegg til to utvidelser som kan brukes ved behov (dcatapno3-range-shapes.ttl og dcatapno3-vocabulary-shapes.ttl).

For eksempel vil en datatilbyder oppgi hvem som er utgiver av datasettbeskrivelsen:

<http://example.com/dataset> dct:publisher <https://organization-catalog.fellesdatakatalog.digdir.no/organizations/123456789> .

organization-catalog-URI-en peker til en autorativ kilde for enheter, noe som er helt korrekt i følge DCAT-AP-NO. Men datatilbyder har ingen kontroll på innholdet i den ressursen, og det er derfor ikke noe poeng for datatilbyder å validere informasjonen på https://organization-catalog.fellesdatakatalog.digdir.no/organizations/123456789

Den nasjonale datakatalogen kan derimot laste inn denne informasjonen, og vil validere at ressursen har all informasjonen som trengs (organisasjonsnummer, virksomhetsnavn, osv.). Reglene som sjekker dette er definert i vocabulary-shapes.ttl.

Hva er de ulike regelsettene?

Core Shapes

Fil: dcatapno3-core-shapes.ttl

Disse reglene sjekker

• Minimums- og maksimumsbruk av egenskaper
• Korrekt bruk av URI, Literal og Blank Node.
• Korrekt bruk av noen klasser som vi antar at alltid følger med beskrivelsen (blant annet dcat:Distribution, adms:Identifier, cv:Cost og kontaktpunkt)

Range Shapes

Fil: dcatapno3-range-shapes.ttl

Disse reglene sjekker at kodene som brukes er i henhold til spesifikasjonen. Reglene baserer seg på mønstergjenkjenning (pattern matching) på URI-en du har oppgitt. Eksempelvis om du har oppgitt lisens, sjekker reglene at URI-en til lisensen du har oppgitt begynner med "http://publications.europa.eu/resource/authority/licence". Det er fortsatt mulig å oppgi feil kode, f.eks. "http://publications.europa.eu/resource/authority/licence/NOT-A-VALID-LICENSE", disse reglene vil ikke fange opp det.

Vocabulary Shapes

Fil: dcatapno3-vocabulary-shapes.ttl

Disse reglene sjekker at selve innholdet i kodene og de eksterne ressursene er korrekt. De sjekker også at kodene du peker til eksisterer og er korrekt. Bruker du disse reglene må du laste inn kodene og inkludere dem i beskrivelsen (RDF-grafen) som skal valideres.

Når skal du bruke hvilke regelsett?

Ønsker du å validere beskrivelsene dine i ditt eget system er trolig Core- og Range-regelsettene det du vil bruke. Disse regelsettene kan brukes uten å laste inn ekstra ressurser (sånn som koder fra kodelister).

Er du ansvarlig for en datakatalog kan det være aktuelt å bruke Vocabulary-regelsettet i tillegg. Men du må da laste inn en hel del informasjon fra eksterne parter for at valideringen skal lykkes. Blant annet gjelder det kodene fra EU sine kodelister og informasjon om enheter fra organization-catalog. Vurder om det er formålstjenlig, eller om du kun skal bruke Core- og Range-regelsettene.

Detaljert om hva reglene dekker

...og hva de ikke dekker

De ulike regelsettene sjekker ulike sider ved datasett- og datatjenestebeskrivelser.

Core-reglene sjekker at:

• Du har oppgitt de obligatoriske egenskapene.
• Du ikke oppgir flere verdier for egenskaper som skal ha maks en verdi.
• Datatypen er riktig, f.eks. at du ikke bruker en verdi (Literal) der hvor du skal bruke en URI
• Egenskaper hvor spesifikasjonen krever det kun har én verdi per språk.
• Du har oppgitt klasser (rdf:type) for noen klasser vi antar at alltid følger med beskrivelsen og er inkludert i grafen som valideres.

Men Core-reglene sjekker ikke bruk av vokabularer, eller typen til ressurser som vi antar befinner seg utenfor beskrivelsen. Som et eksempel vil Core-reglene ikke fange opp om du oppgir en ugyldig lisens for en distribusjon. Om du oppgir http://example.com/non-existent-license i stedet for å peke til en kode fra EU sin License-kodeliste vil Core-reglene ikke gi feilmelding på det.

Core-reglene sjekker heller ikke at verdien til utgiver (dct:publisher) er av type foaf:Agent, slik spesifikasjonen krever. Det er fordi den informasjonen befinner seg hos en ekstern part som du som datatilbyder ikke har ansvar for. Det gir derfor ikke mening å gi deg beskjed om eventuelle feil som ligger hos dem.

Range-reglene sjekker at:

• Rot-URL til kodene du bruker er korrekt.
• Du bruker riktige klasser for noen egenskaper, som odrl:Policy, odrs:RightsStatement og spdx:Checksum. Disse klassene antar vi at følger med beskrivelsen.

I tillegg gir de advarsel og informasjons-feilmelding for egenskaper hvor vi anbefaler bruk av visse kontrollerte vokabularer/kodelister.

Vocabulary-reglene sjekker at:

• Kodene du peker til faktisk er del av riktig kodeliste (med basert på egenskapen skos:inScheme).
• Du bruker riktige klasser for noen egenskaper hvor vi ikke antar at disse ressursene er inkludert i beskrivelsen (ressursene må altså lastes inn for validering).

Hva fanger ikke reglene opp

Det er noen egenskaper hvor DCAT-AP-NO ikke spesifiserer hvilke kontrollerte vokabular du skal bruke. Da er det ingen måte for oss å validere at du bruker den koden du faktisk mente å bruke. Om du mener å peke til koden http://example.com/a-code men gjør en skrivefeil og i stedet for peker til http://example.comm/a-code (en ekstra m) er det ingen måte for reglene å fange opp det. Reglene er altså ikke komplett, de fanger ikke opp alle feil. Men vi har forsøkt å gjøre de så konsistent som mulig, altså at de kun gir feilmelding når det er en reell feil.

I tillegg er det en del sjekker vi ikke gjør lenger. Et eksempel er når du oppgir URL til dokumentasjon for et datasett: <dataset> foaf:page <http://example.com/datasett-dokumentasjon> . I versjon 2 av reglene sjekket vi at ressursen det ble pekt til var av type foaf:Document. Det er strengt tatt nettsiden sitt ansvar selv å angi at det er av typen foaf:Document, og ikke ditt ansvar som datatilbyder, så dette sjekker vi ikke lenger.

Hva er URI og IRI?

En Uniform Resource Identifier er identifikatoren, eller "navnet" til en ressurs i beskrivelsen. I tillegg kan URI-en fungere som en URL hvor du kan slå opp og få svar fra web-ressursen. EN IRI er en Internationalized Resource Identifier. En IRI fungerer på samme måte som en URI, men støtter veldig mange flere tegn, fra flere språk. Vi har valgt å bruke termen URI i feilmeldingene i SHACL-reglene, siden vi antar at den er mer velkjent. Men i realiteten kan du bruke IRI-er som identifikator for ressursene.

Krav om kun en verdi per språk

Noen egenskaper, som tittel og beskrivelse på Datasett og Datatjenester (API-er) kan kun ha én verdi per språk. Du vil få feilmelding om du angir flere verdier på samme språk.

Bruk av blanke noder

Vi har vært noe restriktiv på hvor du kan bruke blanke noder. Om du gjør oppgir URI, altså navn, for ressursen blir det ofte enklere for de som skal konsumere beskrivelsen, sånn som datakataloger og dataportaler. Om du støter på et tilfelle hvor du mener at blanke noder bør tillates, si fra!

"Minst en verdi fra Data Theme"

DCAT-AP (på EU-nivå) har nylig definert at dcat:theme krever at minst én verdi må komme fra vokabularet Data Theme. Det betyr at du kan bruke andre kodelister på denne egenskapen. For datasett, hvor dcat:theme er obligatorisk (1..n) betyr det at du må oppgi minst én verdi fra Data Theme. For datatjenester (API) er dcat:theme ikke obligatorisk (0..n). Det betyr at hvis du oppgir egenskapen dcat:theme på Datatjeneste, så må minst en av verdiene være fra Data Theme.

Identifikator (dct:identifier) må nå være Literal

Reglene for versjon 2 av DCAT-AP-NO tillot URI-er på dct:identifier. I versjon 3 er det nå skjerpet inn og man kan kun angi Literals. Det for å stemme overens med spesifikasjonen.

Hva trigger at en regel kjøres?

SHACL-reglene kjøres per klasse, det vil si at om du uttrykker at en ressurs er av en viss type, med rdf:type <class>, så vil reglene for den klassen kjøres på instansen. For eksempel vil reglene som gjelder for distribusjoner kjøres på ressurser hvor du har oppgitt at typen er rdf:type dcat:Distribution. Det betyr at du ikke skal oppgi typen for eksterne ressurser. For eksempel skal du ikke oppgi at en kode fra EUs kodelister er av typen skos:Concept.

Hvis du kjører resonnering på beskrivelsen din kan det være at noen tripler utledes, bl.a. rdf:type, noe som gjør at reglene kjøres på den instansen. Hvilke tripler som utledes avhenger av ontologien du bruker. Vær obs på at resonnering kan føre til at noen ressurser valideres selv om du i utgangspunktet ikke tenkte å validere dem.

Vanlige feil

Her er eksempler på noen vanlige feil.

Du oppgir en Literal i stedet for en URI

Eksempel på feil i Turtle:

<http://example.com/dataset> dct:format "http://publications.europa.eu/resource/authority/file-type/JSON" .

Dette vil typisk gi en feilmelding som ser slik ut: "The value of property [navn på egenskap] MUST be a URI". Du får feilmeldingen fordi du har oppgitt en tekststreng i stedet for en URI.

Korrigert beskrivelse i Turtle:

<http://example.com/dataset> dct:format <http://publications.europa.eu/resource/authority/file-type/JSON> .

Merk at hermetegnet er erstattet med vinkelparenteser.

Samme eksempel i JSON-LD:

{   "@context": {
        "dct": "http://purl.org/dc/terms/"
    },
    "dct:format": "http://publications.europa.eu/resource/authority/file-type/JSON"
}

Korrigert beskrivelse i JSON-LD:

{ 
    "@context": {
        "dct": "http://purl.org/dc/terms/"
    },
    "dct:format": {"@id": "http://publications.europa.eu/resource/authority/file-type/JSON"}
}

Alternativ fiks i JSON-LD, hvor vi angir i @context-objektet at verdier på dct:format er URI-er:

{
    "@context": {
        "dct": "http://purl.org/dc/terms/",
        "dct:format": {"@type": "@id"}
    },
    "dct:format": "http://publications.europa.eu/resource/authority/file-type/JSON"
}

Du bruker en blank node hvor det ikke er tillatt

Eksempel på feil i Turtle:

<http://example.com/dataset> prov:wasGeneratedBy [ rdf:type skos:Concept, prov:Activity ; skos:notation "PROV" ] .

Dette vil gi en feilmelding som typisk ser slik ut: "The value of property prov:wasGeneratedBy MUST be a URI".

Korrigert beskrivelse i Turtle:

<http://example.com/dataset> prov:wasGeneratedBy <http://example.com/a-provenance-statement> .

<http://example.com/a-provenance-statement> rdf:type skos:Concept, prov:Activity ;
    skos:notation "PROV" .

Du bruker https:// i koder fra EUs kontrollerte vokabularer

Hvis du bruker https:// på egenskaper som krever bruk av kontrollerte vokabularer fra EU vil du få feilmelding som ser slik ut:

"The value of property [navn på egenskap] MUST come from the controlled vocabulary [navn på vokabular]..."

Kodene fra EU begynner med http://.

Eksempel på feil i Turtle:

<http://example.com/dataset> dct:format <https://publications.europa.eu/resource/authority/file-type/JSON> .

Korrigert eksempel i Turtle:

<http://example.com/dataset> dct:format <http://publications.europa.eu/resource/authority/file-type/JSON> .

Du bruker vanlig tekststreng i stedet for språktekst

Noen egenskaper krever at du oppgir språket til en tekst-streng, for eksempel dct:description.

Eksempel på feil i Turtle:

<http://example.com/dataset> dct:description "A description of the dataset" .

Det vil typisk gi en feilmelding som ser slik ut: "The value of property dct:description MUST be of datatype rdf:langString"

Korrigert beskrivelse:

<http://example.com/dataset> dct:description "A description of the dataset"@en .

Legg merke til den ekstra @en som er lagt til.

I JSON-LD kan du angi språk på flere måter. Merk at språkkoden må samsvare med språkkoder fra BCP47

{
    "@context": {
        "dct": "http://purl.org/dc/terms/"
    },
    "dct:description": {
        "@value": "A description of the dataset",
        "@language": "en"
    }
}

{
    "@context": {
        "dct": "http://purl.org/dc/terms/",
        "dct:description": {
            "@container": "@language"
        }
    },
    "dct:description": {
        "en": "A description of the dataset",
        "nb": "En beskrivelse av datasettet"
    }
}

{
    "@context": {
        "dct": "http://purl.org/dc/terms/",
        "english_description": {
            "@id": "dct:description",
            "@language": "en"
        }
    },
    "english_description": "A description of the dataset"
}

Eksempler på bruk

I nettleser

I nettleseren kan du bruke EU sin SHACL-validator, https://www.itb.ec.europa.eu/shacl/any/upload.

Under Content to validate laster du enten opp filen din eller klipper og limer inn beskrivelsen i tekstfeltet. Vær obs på at beskrivelsen da valideres på serveren til Interoperability Test Bed, så ikke last opp informasjon som ikke skal publiseres eller offentliggjøres.

Hvis filen ikke har en filendelse må du velge riktig RDF-format for beskrivelsen i Content Syntax.

Under External Shapes velger du URI og legger til lenken til SHACL-reglene. Velg de som er relevant, for de fleste vil det være:

Core: https://raw.githubusercontent.com/Informasjonsforvaltning/dcat-ap-no/refs/heads/develop/shacl/dcatapno3-core-shapes.ttl

Range: https://raw.githubusercontent.com/Informasjonsforvaltning/dcat-ap-no/refs/heads/develop/shacl/dcatapno3-range-shapes.ttl

Trykk på Validate.

Validatoren tilbys også som REST API.

Med kommandolinjeverktøy

Det finst flere biblioteker og programmer som kan kjøre SHACL-regler. Et av de er Apache Jena. Her finner du også informasjon om hvordan installere kommandolinjeverktøyene: https://jena.apache.org/documentation/tools/

Når du har installert verktøyet shacl og riot fra Jena kan du kjøre validering med disse.

Dette kan være lurt å gjøre i en egen/ny mappe så du ikke overskriver eksisterende filer.

Last ned reglene du skal bruke:

curl https://raw.githubusercontent.com/Informasjonsforvaltning/dcat-ap-no/refs/heads/develop/shacl/dcatapno3-core-shapes.ttl > dcatapno3-core-shapes.ttl

curl https://raw.githubusercontent.com/Informasjonsforvaltning/dcat-ap-no/refs/heads/develop/shacl/dcatapno3-range-shapes.ttl > dcatapno3-range-shapes.ttl

Slå sammen reglene til ett regelsett og skriv dem til filen shapes.ttl:

riot --output=nt dcatapno3-core-shapes.ttl dcatapno3-range-shapes.ttl > shapes.nt

Kjør validering på beskrivelsen som er i filen example-description.ttl:

shacl validate --text --shapes shapes.nt --data example-description.ttl

Du kan droppe --text-argumentet om du ønsker å outputte en RDF-graf som du kan navigere programmatisk gjennom.

Alternativt kan du kjøre reglene i to omganger i stedet for å slå sammen til én graf:

shacl validate --text --shapes dcatapno3-core-shapes.ttl --data example-description.ttl
shacl validate --text --shapes dcatapno3-range-shapes.ttl --data example-description.ttl

---

Endringer:

(02.06.25: Fikset lenke, pekte tidligere til feil validator fra EUs Interoperability Test Bed)