Obě strany předchozí revize Předchozí verze Následující verze | Předchozí verze Následující verzeObě strany příští revize |
standardy:technicke-standardy-pro-vytvareni-datovych-schemat-na-stupni-3 [2017/10/09 13:27] – Jakub Klímek | standardy:technicke-standardy-pro-vytvareni-datovych-schemat-na-stupni-3 [2021/06/14 16:54] – [Table Schema] Jakub Klímek |
---|
Při návrhu datových schémat dodržujte následující pravidla: | Při návrhu datových schémat dodržujte následující pravidla: |
| |
* Pro primitivní datové typy ([[datovy-typ:řetezec|řetězec]], [[datovy-typ:cele-cislo|celé číslo]], [[datovy-typ:datum|datum]], ...) používejte datové typy jazyka XML Schema (i v případě CSV a JSON souborů). | * Pro primitivní datové typy ([[datovy-typ:řetezec|řetězec]], [[datovy-typ:celé-císlo|celé číslo]], [[datovy-typ:datum|datum]], ...) používejte datové typy jazyka XML Schema (i v případě CSV a JSON souborů). |
* Schéma každé distribuce musí být volně dostupné ke stažení v síti WWW. | * Schéma každé distribuce musí být volně dostupné ke stažení v síti WWW. |
* Distribuce se stejnou strukturou mají společné schéma. | * Distribuce se stejnou strukturou mají společné schéma. |
- název v češtině | - název v češtině |
- všechna písmena malá (lower case) | - všechna písmena malá (lower case) |
- žádná diakritika | |
- víceslovné názvy spojené podtržítkem ''_'' | - víceslovné názvy spojené podtržítkem ''_'' |
- hierarchickou vazbu reprezentujte také podtržítkem ''_'', např. ''pokutovany_ic'', ''pokutovany_nazev'' | - hierarchickou vazbu reprezentujte také podtržítkem ''_'', např. ''pokutovaný_ič'', ''pokutovaný_název'' |
- Pro nově definované sloupce použijte vhodný datový typ jazyka XML Schema. | - Pro nově definované sloupce použijte vhodný datový typ jazyka XML Schema. |
| |
Jako jazyk pro definici schématu pro data v CSV můžete použít buďto standard [[https://www.w3.org/TR/tabular-metadata/|Metadata Vocabulary for Tabular Data]] z rodiny standardů W3C [[https://www.w3.org/standards/techs/csv#w3c_all|CSV on the Web]] (CSVW), nebo definici [[https://specs.frictionlessdata.io/table-schema/|Table Schema]]. | Jako jazyk pro definici schématu pro data v CSV použijte standard [[https://www.w3.org/TR/tabular-metadata/|Metadata Vocabulary for Tabular Data]] z rodiny standardů W3C [[https://www.w3.org/standards/techs/csv#w3c_all|CSV on the Web]] (CSVW). |
Oba tyto jazyky říkají, jak má být CSV soubor publikovaný na webu popsán pomocí přídavného JSON souboru, který je publikován spolu s CSV souborem, a liší se pouze syntaxí a expresivitou tohoto JSON souboru. | Standard říká, jak má být CSV soubor publikovaný na webu popsán pomocí přídavného JSON-LD souboru, který je publikován spolu s CSV souborem. |
Doporučujeme však použít standard W3C. | |
| |
==== Metadata Vocabulary for Tabular Data (CSV on the Web, CSVW) ==== | ==== Metadata Vocabulary for Tabular Data (CSV on the Web, CSVW) ==== |
Jednotlivé položky v JSON deskriptoru mají následující význam: | Jednotlivé položky v JSON deskriptoru mají následující význam: |
| |
* Položka ''@context'' musí obsahovat minimálně URL ''http://www.w3.org/ns/csvw'', v tomto případě obsahuje ještě specifikaci češtiny jakožto výchozího jazyka textových položek schématu. | * Položka ''@context'' musí obsahovat minimálně URL ''http://www.w3.org/ns/csvm'', v tomto případě obsahuje ještě specifikaci češtiny jakožto výchozího jazyka textových položek schématu. |
* Položka ''url'' musí obsahovat (relativní či absolutní) URL popisovaného CSV souboru. Každý CSV soubor má tedy vlastní JSON deskriptor. | * Položka ''url'' musí obsahovat (relativní či absolutní) URL popisovaného CSV souboru. Každý CSV soubor má tedy vlastní JSON deskriptor. |
* Položka ''tableSchema'' musí obsahovat buďto URL jiného JSONu se samotným schématem, což je použitelné pro sdílení jednoho schématu více CSV soubory a jejich JSON deskriptory, nebo přímo schéma samotné. | * Položka ''tableSchema'' musí obsahovat buďto URL jiného JSONu se samotným schématem, což je použitelné pro sdílení jednoho schématu více CSV soubory a jejich JSON deskriptory, nebo přímo schéma samotné. |
* Položka ''columns'' obsahuje pole s popisky jednotlivých sloupců | * Položka ''columns'' obsahuje pole s popisky jednotlivých sloupců |
* Položka ''primaryKey'' obsahuje identifikaci primárního klíče v CSV tabulce. To může být buďto jeden sloupec, nebo pole sloupců. | * Položka ''primaryKey'' obsahuje identifikaci primárního klíče v CSV tabulce. To může být buďto jeden sloupec, nebo pole sloupců. |
* Položka ''name'' specifikuje *identifikátor* sloupce v CSV souboru jakožto objektu. Nejedná se o název sloupce v souboru, ten je popsán dále jako jedna z jeho vlastností. | * Položka ''name'' specifikuje *identifikátor* sloupce v CSV souboru jakožto objektu. Nejedná se o název sloupce v souboru, ten je popsán dále jako jedna z jeho vlastností. Musí to být validní část URI, případná diakritika zde tak musí být zakódovaná pomocí procentového kódování. |
* Položka ''titles'' obsahuje jeden či více (jako pole) názvů sloupců v CSV. Lze tedy použít jedno schéma pro více CSV souborů, které mají dokonce různé názvy sloupců, případně v hlavičce používají různé jazyky. | * Položka ''titles'' obsahuje jeden či více (jako pole) názvů sloupců v CSV. Lze tedy použít jedno schéma pro více CSV souborů, které mají dokonce různé názvy sloupců, případně v hlavičce používají různé jazyky. |
* Položka ''dc:description'' obsahuje textový popis významu sloupce. | * Položka ''dc:description'' obsahuje textový popis významu sloupce. |
* Pro datové typy v položce ''datatype'' lze použít [[https://www.w3.org/TR/tabular-metadata/#datatypes|hodnoty založené na datových typech XML Schema]]. | * Pro datové typy v položce ''datatype'' lze použít [[https://www.w3.org/TR/tabular-metadata/#datatypes|hodnoty založené na datových typech XML Schema]]. |
| |
==== JSON Table Schema ==== | Vystavený JSON deskriptor dle CSVW by pak měl být poskytován s HTTP hlavičkou ''Content-Type: application/csvm+json; charset=utf-8'' a pojmenován podle popisovaného souboru, tedy pro ''xxx.csv'' to bude ''xxx.csv-metadata.json''. |
| |
===== Definice vlastního schématu pro data v XML ===== | Toto je jen minimalistický příklad toho, co lze popsat pomocí CSVW. Pro využití všech možností je třeba postupovat dle [[https://www.w3.org/TR/tabular-metadata/|specifikace]]. |
| |
| === Sdílené schéma pro více CSV souborů === |
| Deskriptor CSV souboru lze oddělit od schématu, pokud schéma chceme použít pro více CSV souborů. |
| Pak budeme mít JSON soubor ''schema.json'' se schématem samotným: |
| <code json> |
| { |
| "@context": ["http://www.w3.org/ns/csvw",{"@language": "cs"}], |
| "columns": [{ |
| "name": "idhod", |
| "titles": "idhod", |
| "dc:description":"unikátní identifikátor údaje Veřejné databáze ČSÚ", |
| "required": true, |
| "datatype": "string" |
| }, { |
| "name": "hodnota", |
| "titles": "hodnota", |
| "dc:description":"zjištěná hodnota", |
| "required": true, |
| "datatype": "number" |
| }], |
| "primaryKey": "idhod" |
| } |
| </code> |
| |
| A deskriptor každého CSV souboru se na něj bude odkazovat (nejspíše však pomocí plného, absolutního URL): |
| <code json> |
| { |
| "@context": ["http://www.w3.org/ns/csvw",{"@language": "cs"}], |
| "url": "012052-17data091517.csv", |
| "tableSchema": "schema.json" |
| } |
| </code> |
| |
| === Validace CSVW === |
| CSV popsané pomocí CSVW lze nejjednodušeji validovat nástrojem [[https://csvw.opendata.cz|csvw-validator]]. |
| Ten má jednak sdílené webové rozhraní, a také lze spustit z příkazové řádky nebo použít jako webovou službu. |
| |
| CSV popsané pomocí CSVW lze validovat například pomocí nástroje [[https://github.com/ruby-rdf/rdf-tabular|rdf-tabular]], který stačí nasměrovat na CSV soubor, a v případě nedodržení doporučeného pojmenování JSON deskriptoru i na tento deskriptor. |
| Tedy ''rdf validate xxx.csv'' |
| |
| CSV popsané pomocí CSVW lze validovat například pomocí knihovny [[https://github.com/theodi/csvlint.rb|csvlint.rb]], kterou stačí spustit a nasměrovat na JSON deskriptor, který pak ukazuje na CSV data, případně schéma. Tedy ''csvlint -s schema.json'' pro lokální schéma v souboru v souborovém systému, nebo s plným URL deskriptoru, např. ''csvlint -s https://data.mvcr.gov.cz/soubory/czechpoint/2007.json''. |
| |
| <WRAP center round important 60%> |
| Webové rozhraní [[https://csvlint.io/|csvlint]] doporučení CSV on the Web neumí! |
| </WRAP> |
| |
| |
| |
| ===== Definice vlastního schématu pro data v XML ===== |
| Pro popis XML schématu se používá jazyk XML Schema. |
| |
| Prvním krokem k tvorbě schematu pro XML data je určení toho, jak se budou jmenovat a jak budou zanořeny jednotlivé elementy v XML souboru, jaké budou mít datové typy a jaký budou mít význam. |
| Pro dosažení maximální míry interoperability postupujte v následujících krocích: |
| - Podívejte se na [[vzor:start|již existující standardy]] pro datové sady. |
| - Pokud se některá datová sada shoduje s daty, které chcete publikovat, použijte její předpřipravené schéma. Existující schéma nemusíte daty pokrývat celé, všechny položky jsou volitelné. |
| - Pokud se žádná existující datová sada neshoduje s daty, které chcete publikovat, vytvořte nové schéma. |
| - Pokud některá datová sada pokrývá data která chcete publikovat pouze částečně, použijte v novém schématu pro pokryté položky XML elementy s datovými typy z existujícího XML schématu. |
| - Dosud nepokryté elementy, tj. ty, jejichž význam neodpovídá žádnému datovému typu v žádné existující datové sadě ze vzorových publikačních plánů, pojmenujte dle stejných jmenných konvencí. Tj. |
| - vytvořte si vlastní XML namespace |
| - názvy elementů či atributů v češtině |
| - všechna písmena malá (lower case) |
| - žádná diakritika |
| - víceslovné názvy spojené podtržítkem ''_'' |
| - hierarchickou vazbu reprezentujte vnořeným XML elementem |
| - Pro nově definované elementy použijte vhodný datový typ jazyka XML Schema. |