Abstrakt

Cílem tohoto dokumentu je specifikovat rozhraní lokálních katalogů otevřených dat (LKOD) pro jejich harvestování Národním katalogem otevřených dat (NKOD). Stejná specifikace platí i pro datový model NKOD a data poskytovaná z NKOD v podobě souborů ke stažení či SPARQL endpointu. Nejprve je specifikován datový model katalogizačního záznamu. Poté jsou specifikovány 3 varianty rozhraní pro harvestaci. Varianta CKAN API je podporována v režimu zpětné kompatibility. Dvě varianty jsou založeny na standardu DCAT-AP v1.2, jedna využívá SPARQL endpoint a jedna specifikuje variantu uložení záznamů v souborech, bez použití SPARQL endpointu.

Úvod

Provozování lokálního katalogu otevřených dat (LKOD) je jedním ze způsobů zajištění katalogizace dat v Národním katalogu otevřených dat (NKOD), což je jedna ze zákonných podmínek pro to, aby data mohla být nazývána otevřenými daty. Tento způsob katalogizace je vhodný pro střední a větší organizace, u kterých se dá předpokládat katalogizace většího množství datových sad či častější aktualizace jejich metadat.

Položky metadatového záznamu

V této sekci jsou popsány položky, které mohou být evidované v Národním katalogu otevřených dat (NKOD) pro každou datovou sadu a její distribuci. Položky se řídí standardem DCAT Application Profile for data portals in Europe Version 1.2 (DCAT-AP v1.2). Jedná se o standard založený na propojených datech, předpokládá se tedy znalost Otevřené formální normy Propojená data.

DCAT-AP v1.2 rozlišuje dva základní typy entit, datovou sadu, a její distribuci. Metadata datové sady ji popisují bez ohledu na konkrétní reprezentaci jejích dat. Ta je popsána jako distribuce datové sady. Distribucí může mít datová sada více, lišit se ale mohou pouze formátem souboru ke stažení (např. CSV či JSON). Informačně by distribuce měly být ekvivalentní.

Použité prefixy

V popisu položek a rozhraní budou použity následující prefixy slovníků.

Pro přehlednost zápisu budou použity ještě následující prefixy zkracující IRI vzorových entit.

Třída: Datová sada

Jméno
Datová sada
Popis
Konceptuální entita reprezentující poskytovanou informaci.
Třída
sada: a dcat:Dataset .

Název datové sady

Jméno
Název datové sady
Popis
Tato vlastnost obsahuje název datové sady.
Vlastnost
dct:title
Typ
Text
Povinnost
Povinná
Příklad
sada: dct:title "Kontroly plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení"@cs .

Popis datové sady

Jméno
Popis datové sady
Popis
Tato vlastnost obsahuje volný text s popisem datové sady.
Vlastnost
dct:description
Typ
Text
Povinnost
Povinná
Příklad
sada: dct:description "Statistika kontrol plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení od roku 2009"@cs .

Téma datové sady

Jméno
Téma datové sady
Popis
Tato vlastnost odkazuje na kategorii či téma datové sady. Datová sada může být popsána více tématy.
Vlastnost
dcat:theme
Typ
IRI položky z evropského číselníku datových témat
Povinnost
Povinná
Příklad
sada: dcat:theme <http://publications.europa.eu/resource/authority/data-theme/TRAN> .

Periodicita aktualizace

Jméno
Periodicita aktualizace
Popis
Tato vlastnost odkazuje na frekvenci, se kterou je datová sada aktualizována.
Vlastnost
dct:accrualPeriodicity
Typ
IRI položky z evropského číselníku frekvencí
Povinnost
Povinná
Příklad
sada: dct:accrualPeriodicity <http://publications.europa.eu/resource/authority/frequency/MONTHLY> .

Klíčová slova

Jméno
Klíčová slova
Popis
Tato vlastnost obsahuje klíčové slovo nebo značku popisující datovou sadu.
Vlastnost
dcat:keyword
Typ
Text, opakovaná vlastnost.
Povinnost
Povinná
Příklad
sada: dcat:keyword "kontrola"@cs, "statistika"@cs .

Související geografické území - prvek z RÚIAN

Jméno
Související geografické území - prvek z RÚIAN
Popis
Tato vlastnost odkazuje na geografickou oblast pokrytou datovou sadou.
Vlastnost
dct:spatial
Typ
IRI územního prvku RÚIAN
Povinnost
Povinná
Příklad
sada: dct:spatial <https://linked.cuzk.cz/resource/ruian/stat/1> .

Časové pokrytí

Jméno
Časové pokrytí
Popis
Tato vlastnost odkazuje na časový úsek pokrytý datovou sadou.
Vlastnost
dct:temporal
Typ
Entita typu dct:PeriodOfTime s vlastnostmi schema:startDate a schema:endDate, které mají datový typ xsd:date.
Povinnost
Nepovinná
Příklad
sada: dct:temporal čas: .

čas: schema:startDate "2009-01-01"^^xsd:date ;
     schema:endDate "2017-12-31"^^xsd:date .

Kotaktní bod - jméno a email

Jméno
Kontaktní bod - jméno a email
Popis
Tato vlastnost obsahuje kontaktní informace, které mohou být využity pro zasílání připomínek k datové sadě.
Vlastnost
dcat:contactPoint
Typ
Entita podtypu vcard:Kind s vlastnostmi vcard:fn a vcard:hasEmail.
Povinnost
Nepovinná
Příklad
sada: dcat:contactPoint kurátor: .

kurátor: a vcard:Individual ;
         vcard:fn "Jan Novák"@cs ;
         vcard:hasEmail "jan.novak@organizace.cz" .

Odkaz na dokumentaci datové sady

Jméno
Odkaz na dokumentaci datové sady
Popis
Tato vlastnost odkazuje na stránku nebo dokument o datové sadě.
Vlastnost
foaf:page
Typ
IRI webové stránky dokumentace.
Povinnost
Nepovinná
Příklad
sada: foaf:page <https://data.cssz.cz/documentation/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni> .

Klasifikace dle EuroVoc

Jméno
Klasifikace dle EuroVoc
Popis
Tato vlastnost odkazuje na kategorii či téma datové sady dle EuroVoc. Datová sada může být popsána více tématy.
Vlastnost
dcat:theme
Typ
IRI konceptu z evropského tezauru EuroVoc
Povinnost
Nepovinná
Příklad
sada: dcat:theme <http://eurovoc.europa.eu/1001>, <http://eurovoc.europa.eu/4050> .

Distribuce datové sady

Jméno
Distribuce datové sady
Popis
Tato vlastnost odkazuje z datové sady na její distribuci.
Vlastnost
dcat:distribution
Typ
IRI distribuce datové sady.
Povinnost
Povinná
Příklad
sada: dcat:distribution distribuce: .

Třída: Distribuce datové sady

Jméno
Distribuce datové sady
Popis
Fyzická podoba datové sady v konkrétním formátu.
Třída
distribuce: a dcat:Distribution.

Specifikace podmínek užití

Jméno
Specifikace podmínek užití
Popis
Tato vlastnost odkazuje na strukturovaný popis podmínek užití této distribuce datové sady. Hodnoty se řídí návodem na stanovení podmínek užití.
Vlastnost
pú:specifikace
Typ
Entita typu pú:Specifikace s vlastnostmi pú:autorské-dílo, pú:databáze-jako-autorské-dílo, pú:databáze-chráněná-zvláštními-právy a pú:osobní-údaje.
Povinnost
Povinná
Příklad
distribuce: pú:specifikace podmínky: .

podmínky: a pú:Specifikace ;
          pú:autorské-dílo <https://data.gov.cz/podmínky-užití/neobsahuje-autorská-díla/> ;
          pú:databáze-jako-autorské-dílo <https://data.gov.cz/podmínky-užití/není-autorskoprávně-chráněnou-databází/> ;
          pú:databáze-chráněná-zvláštními-právy <https://data.gov.cz/podmínky-užití/není-chráněna-zvláštním-právem-pořizovatele-databáze/> ;
          pú:osobní-údaje <https://data.gov.cz/podmínky-užití/neobsahuje-osobní-údaje/> .

Odkaz na stažení distribuce datové sady

Jméno
Odkaz na stažení distribuce datové sady
Popis
Tato vlastnost obsahuje URL, které je přímým odkazem na stažitelný soubor v daném formátu.
Vlastnost
dcat:downloadURL
Typ
URL souboru ke stažení.
Povinnost
Povinná
Příklad
distribuce: dcat:downloadURL <https://data.cssz.cz/dump/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni.csv> .

Formát souboru ke stažení

Jméno
Formát souboru ke stažení
Popis
Tato vlastnost odkazuje na typ souboru s distribucí.
Vlastnost
dct:format
Typ
IRI položky z evropského číselníku typů souboru
Povinnost
Povinná
Příklad
distribuce: dct:format <http://publications.europa.eu/resource/authority/file-type/CSV> .

Media type souboru ke stažení

Jméno
Media type souboru ke stažení
Popis
Tato vlastnost odkazuje na typ média distribuce tak, jak je definováno v oficiálním rejstříku typů médií spravovaném IANA [[!IANA-MEDIA-TYPES]].
Vlastnost
dcat:mediaType
Typ
IRI Media type z rejstříku IANA.
Povinnost
Povinná
Příklad
distribuce: dcat:mediaType <http://www.iana.org/assignments/media-types/text/csv> .

Odkaz na strojově čitelné schéma souboru ke stažení

Jméno
Odkaz na strojově čitelné schéma souboru ke stažení
Popis
Tato vlastnost odkazuje na ustanovené schéma, jímž se popisovaná distribuce řídí.
Vlastnost
dct:conformsTo
Typ
URL schématu.
Povinnost
Nepovinná
Příklad
distribuce: dct:conformsTo <https://data.cssz.cz/dump/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni-schema.json> .

Název distribuce datové sady

Jméno
Název distribuce datové sady
Popis
Tato vlastnost obsahuje název distribuce.
Vlastnost
dct:title
Typ
Text
Povinnost
Nepovinná
Příklad
distribuce: dct:title "Kontroly plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení v CSV"@cs .

Rozhraní DCAT-AP SPARQL Endpoint

Toto rozhraní předpokládá, že metadata datových sad dle této specifikace jsou uložena a přístupná ve SPARQL Endpointu. Po registraci tohoto SPARQL endpointu se na něm NKOD zeptá nejprve na seznam instancí třídy dcat:Dataset, a poté se po skupinách bude ptát na povinné, nepovinné i další položky jednotlivých datových sad dle této specifikace a specifikace DCAT-AP v1.2. Jedná se o nejjednodušší způsob registrace lokálního katalogu otevřených dat.

Rozhraní DCAT-AP Dokumenty

Tato varianta rozhraní je určena pro instituce, které nechtějí nebo nemohou provozovat pro účely harvestace metadat o datových sadách do NKOD SPARQL endpoint. Počítá se serializací metadat o datových sadách do souborů umístěných na web podobně, jako varianta CKAN API, ale s využitím standardu DCAT-AP v1.2. Jako indexový soubor pak poslouží soubor obsahující instanci třídy dcat:Catalog, která pomocí vlastnosti dcat:dataset ukazuje na URL jednotlivých datových sad. Při přístupu na tato URL datových sad NKOD předpokládá, že v odpovědi dostane kompletní katalogizační záznam pro danou datovou sadu, včetně jejích distribucí.

Soubor katalogu

Soubor katalogu je soubor v serializaci Turtle, který obsahuje instanci třídy dcat:Catalog a odkazy na jednotlivé katalogizované datové sady.

Soubor datové sady

Na URL specifikovaných v souboru katalogu pak NKOD očekává soubory v serializaci Turtle obsahující kompletní metadatový záznam datové sady, včetně distribucí.

Rozhraní CKAN API

CKAN API je rozhraní nejrozšířenější implementace datového katalogu, CKAN. Je založené na formátu JSON [[!ECMA-404]], a obsahuje dvě hlavní funkce, package_list a package_show. Toto rozhraní je implemetováno samotným katalogem CKAN a také katalogem DKAN. Pro instituce, které nemohou nebo nechtějí provozovat celé katalogizační řešení postačí, když budou CKAN API simulovat pomocí statických JSON souborů umístěných na odpovídající URL [[!URL]].

Rozhraní CKAN API je podporováno jen v režimu zpětné kompatibility, což znamená, že se již nebude rozšiřovat o nové položky či funkcionality. Doporučujeme tedy použít jedno z ostatních rozhraní LKOD založených na standardu DCAT-AP v1.2.

Rozhraní CKAN API je pro NKOD rozšířeno o některé metadatové položky inspirované standardem DCAT-AP. Bez nich bude metadatový záznam z hlediska NKOD neúplný. Jsou k dispozici vzorová rozšíření pro CKAN a rozšíření pro DKAN, která lze využít pro předávání úplných metadatových záznamů tímto rozhraním.

Funkce package_list

Tato funkce vrací seznam identifikátorů jednotlivých datových sad registrovaných v LKOD. Tyto identifikátory se pak předávají funkci package_show v parametru id. Identifikátory mohou obsahovat písmena, čísla, pomlčky a podtržítka. Nesmí však obsahovat mezeru.

Funkce package_show

Tato funkce vrací metadatový záznam pro datovou sadu, jejíž identifikátor je předán v parametru id.

Datová sada

V této sekci jsou popsány položky týkající se datové sady ve funkci package_show.

Název datové sady
Vlastnost
title
Typ
Řetězec
Jméno
Název datové sady
Povinnost
Povinná
Příklad
Kontroly, Vystavené faktury
Popis datové sady
Vlastnost
notes
Typ
Řetězec
Jméno
Popis datové sady
Povinnost
Povinná
Příklad
Seznam kontrol od 1.1.2012
Periodicita aktualizace
Vlastnost
frequency
Typ
Řetězec dle EU slovníku pro frekvence. V minulosti to bylo dle ISO 8601, ale to již nedoporučujeme kvůli kompatibilitě s evropským slovníkem.
Jméno
Periodicita aktualizace
Povinnost
Povinná
Příklad
ANNUAL, WEEKLY
Související geografické území - typ prvku RÚIAN
Vlastnost
ruian_type
Typ
Řetězec dle číselníku Typy prvků, územních prvků a územně evidenčních jednotek
Jméno
Související geografické území - typ prvku RÚIAN
Povinnost
Povinná
Příklad
ST, OB
Související geografické území - kód prvku RÚIAN
Vlastnost
ruian_code
Typ
Řetězec obsahující kód prvku RÚIAN
Jméno
Související geografické území - kód prvku RÚIAN
Povinnost
Povinná
Příklad
1, 502235
Klasifikace dle EuroVoc
Vlastnost
theme
Typ
Seznam URL oddělený mezerou
Jméno
Klasifikace dle EuroVoc
Povinnost
Nepovinná
Příklad
http://eurovoc.europa.eu/171 http://eurovoc.europa.eu/695
Email Kurátora dat
Vlastnost
maintainer_email
Typ
E-mailová adresa
Jméno
Email Kurátora dat
Povinnost
Nepovinná
Příklad
verejnadata@instituce.cz
Jméno Kurátora dat
Vlastnost
maintainer
Typ
Řetězec
Jméno
Jméno Kurátora dat
Povinnost
Nepovinná
Příklad
Jan Novák
Odkaz na dokumentaci datové sady
Vlastnost
schema
Typ
URL [[!URL]] webové stránky
Jméno
Odkaz na dokumentaci datové sady
Povinnost
Nepovinná
Příklad
https://www.INSTITUCE.cz/open-data/dokumentace-ds1.html
Klíčová slova
Vlastnost
tags
Typ
Pole objektů s vlastností name
Jméno
Klíčová slova
Povinnost
Povinná
Příklad
"tags": [
{"name": "kontroly"},
{"name": "sankce"}
]
Dotčené časové období od
Vlastnost
temporal_start
Typ
Datum
Jméno
Dotčené časové období od
Povinnost
Nepovinná
Příklad
2012-01-01
Dotčené časové období do
Vlastnost
temporal_end
Typ
Datum
Jméno
Dotčené časové období do
Povinnost
Nepovinná
Příklad
2014-12-31
Distribuce datové sady
Vlastnost
resources
Typ
Pole objektů, viz Distribuce
Jméno
Distribuce datové sady
Povinnost
Povinná

Distribuce datové sady

V této sekci jsou popsány položky týkající se distribuce datové sady ve funkci package_show.

Odkaz na stažení souboru
Vlastnost
url
Typ
URL [[!URL]]
Jméno
Odkaz na stažení distribuce datové sady
Povinnost
Povinná
Příklad
https://www.INSTITUCE.cz/open-data/kontroly.trig
Media type souboru ke stažení
Vlastnost
format
Typ
Řetězec obsahující Media type dle IANA [[!IANA-MEDIA-TYPES]]
Jméno
Media type souboru ke stažení
Povinnost
Povinná
Příklad
application/trig
Název distribuce datové sady
Vlastnost
name
Typ
Řetězec
Jméno
Název distribuce datové sady
Povinnost
Nepovinná
Příklad
Kontroly v RDF TriG
Odkaz na strojově čitelné schéma souboru ke stažení
Vlastnost
describedBy
Typ
URL [[!URL]]
Jméno
Odkaz na strojově čitelné schéma souboru ke stažení
Povinnost
Nepovinná
Příklad
https://www.INSTITUCE.cz/open-data/ontologie.trig

URL funkcí package_list a package_show

URL funkcí package_list a package_show musí splňovat pravidlo, které zajistí, že NKOD na základě URL package_list najde URL funkce package_show. Toto pravidlo je automaticky splněno při použití CKAN či DKAN. Pokud ale instituce CKAN API simuluje statickými soubory, je třeba se ujistit, že je stále dodrženo.

URL funkce package_show se z URL funkce package_list získá odstraněním části od posledního lomítka, a přidáním textu package_show?id= a id datové sady, které vrátila funkce package_list.

Příklady lokálních katalogů s CKAN API

V této sekci uvádíme příklady katalogů užívajících rozhraní CKAN API. Ne všechny katalogy ho ovšem používá správně. Závazné je použití dle této specifikace.