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.
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.
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í.
V popisu položek a rozhraní budou použity následující prefixy slovníků.
adms: http://www.w3.org/ns/adms#
dcat: http://www.w3.org/ns/dcat#
dct: http://purl.org/dc/terms/
foaf: http://xmlns.com/foaf/0.1/
owl: http://www.w3.org/2002/07/owl#
rdfs: http://www.w3.org/2000/01/rdf-schema#
schema: http://schema.org/
skos: http://www.w3.org/2004/02/skos/core#
spdx: http://spdx.org/rdf/terms#
xsd: http://www.w3.org/2001/XMLSchema#
vcard: http://www.w3.org/2006/vcard/ns#
pú: https://data.gov.cz/slovník/podmínky-užití/
Pro přehlednost zápisu budou použity ještě následující prefixy zkracující IRI vzorových entit.
sada: https://data.gov.cz/zdroj/datová-sada/1
distribuce: https://data.gov.cz/zdroj/datová-sada/1/distribuce/1
čas: https://data.gov.cz/zdroj/datová-sada/1/časové-pokrytí
kurátor: https://data.gov.cz/zdroj/datová-sada/1/kontaktní-bod
podmínky: https://data.gov.cz/zdroj/datová-sada/1/distribuce/1/podmínky-užití
sada: a dcat:Dataset .
dct:title
sada: dct:title "Kontroly plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení"@cs .
dct:description
sada: dct:description "Statistika kontrol plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení od roku 2009"@cs .
dcat:theme
sada: dcat:theme <http://publications.europa.eu/resource/authority/data-theme/TRAN> .
dct:accrualPeriodicity
sada: dct:accrualPeriodicity <http://publications.europa.eu/resource/authority/frequency/MONTHLY> .
dcat:keyword
sada: dcat:keyword "kontrola"@cs, "statistika"@cs .
dct:spatial
sada: dct:spatial <https://linked.cuzk.cz/resource/ruian/stat/1> .
dct:temporal
dct:PeriodOfTime
s vlastnostmi schema:startDate
a schema:endDate
, které mají datový typ xsd:date
.
sada: dct:temporal čas: . čas: schema:startDate "2009-01-01"^^xsd:date ; schema:endDate "2017-12-31"^^xsd:date .
dcat:contactPoint
vcard:Kind
s vlastnostmi vcard:fn
a vcard:hasEmail
.
sada: dcat:contactPoint kurátor: . kurátor: a vcard:Individual ; vcard:fn "Jan Novák"@cs ; vcard:hasEmail "jan.novak@organizace.cz" .
foaf:page
sada: foaf:page <https://data.cssz.cz/documentation/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni> .
dcat:theme
sada: dcat:theme <http://eurovoc.europa.eu/1001>, <http://eurovoc.europa.eu/4050> .
dcat:distribution
sada: dcat:distribution distribuce: .
distribuce: a dcat:Distribution.
pú:specifikace
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
.
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/> .
dcat:downloadURL
distribuce: dcat:downloadURL <https://data.cssz.cz/dump/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni.csv> .
dct:format
distribuce: dct:format <http://publications.europa.eu/resource/authority/file-type/CSV> .
dcat:mediaType
distribuce: dcat:mediaType <http://www.iana.org/assignments/media-types/text/csv> .
dct:conformsTo
distribuce: dct:conformsTo <https://data.cssz.cz/dump/kontroly-plneni-povinnosti-zamestnavatelu-v-oblasti-socialniho-zabezpeceni-schema.json> .
dct:title
distribuce: dct:title "Kontroly plnění povinností zaměstnavatelů v oblasti sociálního zabezpečení v CSV"@cs .
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.
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 je soubor v serializaci Turtle, který obsahuje instanci třídy dcat:Catalog
a odkazy na jednotlivé katalogizované 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í.
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.
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.
package_show
Tato funkce vrací metadatový záznam pro datovou sadu, jejíž identifikátor je předán v parametru id
.
V této sekci jsou popsány položky týkající se datové sady ve funkci package_show
.
title
Kontroly
, Vystavené faktury
notes
Seznam kontrol od 1.1.2012
frequency
ANNUAL
, WEEKLY
ruian_type
ST
, OB
ruian_code
1
, 502235
theme
http://eurovoc.europa.eu/171 http://eurovoc.europa.eu/695
maintainer_email
verejnadata@instituce.cz
maintainer
Jan Novák
schema
https://www.INSTITUCE.cz/open-data/dokumentace-ds1.html
temporal_start
2012-01-01
temporal_end
2014-12-31
resources
V této sekci jsou popsány položky týkající se distribuce datové sady ve funkci package_show
.
url
https://www.INSTITUCE.cz/open-data/kontroly.trig
format
application/trig
license_link
https://data.gov.cz/podmínky-užití/volný-přístup/
Dle standardu DCAT [[vocab-dcat]] jsou podmínky užití vlastností distribuce datové sady, jelikož každá distribuce může mít podmínky jiné.
Položku license_link
lze uvést i v poli datové sady result
, pak se interpretuje jako že jsou podmínky užití stejné pro všechny distribuce datové sady.
name
Kontroly v RDF TriG
describedBy
https://www.INSTITUCE.cz/open-data/ontologie.trig
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
.
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.