Základní datové typy

Abstrakt

Tento dokument je sdílenou specifikací pro základní datové typy pro použití v otevřených formálních normách ve smyslu § 3a odst. 3 zákona č. 106/1999 Sb., o svobodném přístupu k informacím. Specifikace je ilustrována příklady dat ve formátech JSON-LD [[json-ld11]] a tedy i JSON [[ECMA-404]], XML [[xml]], CSV [[rfc4180]] a RDF Turtle [[turtle]].

Specifikace

Základní datové typy dělíme na jednoduché, které již dále nejsou strukturovány, a složené, které se dělí na více položek.

Jednoduché datové typy

Jednoduché datové typy se už dále nedělí na jednotlivé položky. Pokud jsou strukturované, je jejich struktura určena již pouze syntaxí použitého datového typu.

Booleovská hodnota - Ano či ne

Booleovská hodnota se hodí pro reprezentaci vlastností, které mohou mít pouze dvě hodnoty - Ano či ne. Ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] se pro reprezentaci booleovské hodnoty používá typ xsd:boolean z jazyka XML Schema [[!xmlschema11-2-20120405]]. Hodnota true vyjadřuje Ano, false vyjadřuje Ne.

{
    "zaplaceno": false,
    "přijato": true
}

<zaplaceno>false</zaplaceno>
<přijato>true</přijato>

zaplaceno,přijato
false,true

faktura:A123 faktura:zaplaceno false ;
             faktura:přijato true .

Nepoužívejte hodnoty jako Ano, 1, yes a podobně. Znesnadňujete tím použití dat.

Datum

Pro reprezentaci datumu se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:date z jazyka XML Schema [[!xmlschema11-2-20120405]]. Tento datový typ umožňuje i explicitně zaznamenat časovou zónu. To se hodí například pro data, u kterých se dá předpokládat využití v jiné časové zóně.

{
    "zaplaceno": "2019-01-01",
    "přijato": "2019-01-01+01:00"
}

<zaplaceno>2019-01-01</zaplaceno>
<přijato>2019-01-01+01:00</přijato>

zaplaceno,přijato
2019-01-01,2019-01-01+01:00

faktura:A123 faktura:zaplaceno "2019-01-01"^^xsd:date ;
             faktura:přijato "2019-01-01+01:00"^^xsd:date .

Nepoužívejte hodnoty v jiných tvarech jako třeba 1. ledna 2019, 01-01-2019 a podobně. Znesnadňujete tím použití dat.

Čas

Pro reprezentaci času se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:time z jazyka XML Schema [[!xmlschema11-2-20120405]]. Tento datový typ umožňuje i explicitně zaznamenat časovou zónu. To se hodí například pro časy, u kterých se dá předpokládat využití v jiné časové zóně.

{
    "zaplaceno": "09:30:00",
    "přijato": "09:30:10.5+01:00"
}

<zaplaceno>09:30:00</zaplaceno>
<přijato>09:30:10.5+01:00</přijato>

zaplaceno,přijato
09:30:00,09:30:10.5+01:00

faktura:A123 faktura:zaplaceno "09:30:00"^^xsd:time ;
             faktura:přijato "09:30:10.5+01:00"^^xsd:time .

Nepoužívejte hodnoty v jiných tvarech jako třeba 09:30, 9:30 a podobně. Znesnadňujete tím použití dat.

Datum a čas

Pro reprezentaci data a času jakožto jedné hodnoty se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:dateTimeStamp z jazyka XML Schema [[!xmlschema11-2-20120405]]. Tento datový typ vyžaduje explicitně zaznamenat časovou zónu. Syntakticky se jedná se o spojení datových typů Datum a Čas pomocí znaku T.

{
    "zaplaceno": "2019-01-01T09:30:00+02:00",
    "přijato": "2019-01-01T09:30:10.5+01:00"
}

<zaplaceno>2019-01-01T09:30:00+02:00</zaplaceno>
<přijato>2019-01-01T09:30:10.5+01:00</přijato>

zaplaceno,přijato
2019-01-01T09:30:00+02:00,2019-01-01T09:30:10.5+01:00

faktura:A123 faktura:zaplaceno "2019-01-01T09:30:00+02:00"^^xsd:dateTimeStamp ;
             faktura:přijato "2019-01-01T09:30:10.5+01:00"^^xsd:dateTimeStamp .

Nepoužívejte hodnoty v jiných tvarech jako třeba 2019-01-01 09:30 (chybný oddělovač, neúplný čas), 1. ledna 2019 v 9:30 a podobně. Znesnadňujete tím použití dat.

Celé číslo

Pro reprezentaci celých čísel se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:integer z jazyka XML Schema [[!xmlschema11-2-20120405]].

{
    "zaplaceno": 4,
    "přijato": 8
}

<zaplaceno>15</zaplaceno>
<přijato>16</přijato>

zaplaceno,přijato
23,42

faktura:A123 faktura:zaplaceno 4 ;
             faktura:přijato "8"^^xsd:integer .

Nepoužívejte hodnoty v jiných tvarech jako třeba 4 815 (s oddělovačem) a podobně. Znesnadňujete tím použití dat.

Desetinné číslo

Pro reprezentaci desetinných čísel se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:double z jazyka XML Schema [[!xmlschema11-2-20120405]]. Oddělovačem desetinných míst je . - tečka.

{
    "zaplaceno": 4.25,
    "přijato": 8.25
}

<zaplaceno>4.25</zaplaceno>
<přijato>8.25</přijato>

zaplaceno,přijato
4.25,8.25

faktura:A123 faktura:zaplaceno 4.25 ;
             faktura:přijato 8.25 .

Nepoužívejte hodnoty v jiných tvarech jako třeba 4,24 (chybný oddělovač desetinných míst) a podobně. Znesnadňujete tím použití dat.

URI, IRI, URL

Pro reprezentaci webových identifikátorů a odkazů URI, IRI a URL se ve všech cílových otevřených formátech, tj. JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]], CSV [[!rfc4180]] a RDF Turlte [[!turtle]] používá typ xsd:anyURI z jazyka XML Schema [[!xmlschema11-2-20120405]]. URI, IRI ani URL nesmí obsahovat nezakódované mezery.

{
    "stránka": "https://data.gov.cz/"
}

<stránka>https://data.gov.cz/</stránka>

stránka
https://data.gov.cz/

faktura:A123 faktura:stránka "https://data.gov.cz/"^^xsd:anyURI ;
             faktura:zdroj <https://data.gov.cz/> .

Řetězec

Pro reprezentaci kódů a jiných jednoduchých hodnot, kterým neodpovídá žádný existující datový typ z jazyka XML Schema [[!xmlschema11-2-20120405]], se použije xsd:string v kódování UTF-8. U všech formátů je třeba dodržovat pravidla pro nahrazování speciálních znaků, které se v textech mohou vyskytovat. Pokud se ale jedná o text v přirozeném jazyce, jako je název, popis apod., je třeba využít datový typ text v přirozeném jazyce.

{
    "kód": "AA-23",
}

<kód>AA-23</kód>

kód
AA-23

:A123 skos:notation "AA-23" .

Text

Pro texty v přirozeném jazyce je třeba specifikovat, v jakém jazyce jsou. Tato informace se pak dá využít ve vícejazyčných aplikacích či automatických překladačích.

Ve formátu JSON je třeba dodržet schéma pro vícejazyčné texty. Pokud může být textových hodnot v daném jazyce více, je třeba dodržet schéma pro více vícejazyčných textů.

{
    "název": {
        "cs": "Název faktury",
        "en": "Label of the invoice"
    }
}

{
    "název": {
        "cs": [
            "Český název",
            "Jiný český název"
        ],
        "en": [
            "English label",
            "Another English label"
        ]
    }
}

Formáty XML a RDF umožňují přímo v datech specifikovat, ve kterém jazyce text je.

<název xml:lang="cs">Název faktury</název>
<název xml:lang="en">Label of the invoice</název>

faktura:A123 faktura:název "Název faktury"@cs, "Label of the invoice"@en .

U formátu CSV je toto možno specifikovat pro každý sloupec ve schématu souboru, a také promítnout v názvu sloupce.

název_cs,název_en
Název faktury,"Label of the invoice"

Složené datové typy

Složené datové typy se dále dělí na položky, které je pro úplné určení hodnoty třeba uvést.

Množství

Pro reprezentaci množství je třeba vždy uvést dvě položky - hodnotu a jednotku množství.

Hodnota

Vlastnost: hodnota
Typ: Desetinné číslo
Jméno: Hodnota množství
Příklad: 12400.21

Jednotka

Pro specifikaci jednotky množství je třeba použít číselník UN/CEFACT Common Codes.

Vlastnost: jednotka
Typ: Řetězec
Jméno: Jednotka množství
Příklad: KGM

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/množství.jsonld",
    "typ": "Množství",
    "hodnota": 23.0,
    "jednotka": "KGM"
}

<množství>
   <hodnota>23.0</hodnota>
   <jednotka>KGM</jednotka>
</množství>

množství_hodnota,množství_jednotka
23.0,KGM

V datovém formátu RDF se pro specifikaci množství používá třída gr:QuantitativeValue ze slovníku GoodRelations.

@prefix gr: <http://purl.org/goodrelations/v1#> .
                        
faktura:A123 faktura:množství množství: .

množství: a gr:QuantitativeValue ;
           gr:hasUnitOfMeasurement "KGM"^^xsd:string ;
           gr:hasValue 23.0 .

Množství bez určení jednotky jsou těžko interpretovatelná. Při určování jednotky je třeba dodržet kódy z číselníku UN/CEFACT Common Codes, jinak se zesložiťuje použití dat.

Částka a jednotková částka

Pro reprezentaci peněžních částek je třeba vždy uvést výši částky a měnu částky. Pokud se jedná o jednotkovou částku, pak se také uvede jednotka.

Výše

Vlastnost: výše
Typ: Desetinné číslo
Jméno: Výše částky.
Příklad: 12400.21

Měna

Pro určení měny je třeba použít IRI z evropského číselníku měn z EU Vocabularies.

Vlastnost: měna
Typ: IRI z evropského číselníku měn z EU Vocabularies.
Jméno: Měna částky
Příklad: http://publications.europa.eu/resource/authority/currency/CZK

Jednotka

Pro specifikaci jednotky množství je třeba použít číselník UN/CEFACT Common Codes.

Vlastnost: jednotka
Typ: Řetězec
Jméno: Jednotka ceny.
Příklad: KGM

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/částka.jsonld",
    "typ": "Částka",
    "výše": 48151623.42,
    "měna": "http://publications.europa.eu/resource/authority/currency/CZK"
}

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/jednotková-částka.jsonld",
    "typ": "Jednotková částka",
    "výše": 48151623.42,
    "měna": "http://publications.europa.eu/resource/authority/currency/CZK",
    "jednotka": "KGM"
}

<zaplaceno>
   <výše>48151623.42</výše>
   <měna>http://publications.europa.eu/resource/authority/currency/CZK</měna>
</zaplaceno>

zaplaceno_výše,zaplaceno_měna
48151623.42,http://publications.europa.eu/resource/authority/currency/CZK

V datovém formátu RDF se pro specifikaci ceny používá třída gr:PriceSpecification ze slovníku GoodRelations. Jelikož je již starší, tak jako specifikaci měny používá její kód formou řetězce. Ten lze do dat přidat pro zpětnou kompatibilitu, ale potřeba je zejména uvést měnu ve formě IRI z příslušného evropského číselníku.

@prefix gr: <http://purl.org/goodrelations/v1#> .
@prefix pojem: <https://slovník.gov.cz/generický/částky/pojem/> .
                        
faktura:A123 gr:hasPriceSpecification zaplaceno: .

zaplaceno: a gr:PriceSpecification ;
           gr:hasCurrency "CZK"^^xsd:string ;
           pojem:má-měnu <http://publications.europa.eu/resource/authority/currency/CZK> ;
           gr:hasCurrencyValue 48151623.42 .

@prefix gr: <http://purl.org/goodrelations/v1#> .
@prefix pojem: <https://slovník.gov.cz/generický/částky/pojem/> .
                        
faktura:A124 gr:hasPriceSpecification zaplaceno: .

zaplaceno: a gr:UnitPriceSpecification ;
           gr:hasCurrency "CZK"^^xsd:string ;
           pojem:má-měnu <http://publications.europa.eu/resource/authority/currency/CZK> ;
           gr:hasCurrencyValue 24.42 ;
           gr:hasUnitOfMeasurement "KGM"^^xsd:string .

Částky bez určení měny jsou těžko interpretovatelné. Při určování měny je třeba dodržet kódy z evropského číselníku, jinak se zesložiťuje použití dat.

Časový okamžik

Pro reprezentaci časových okamžiků lze použít datum, kombinaci data a času a nebo říci, že je časový okamžik nespecifikován. Pokud je jasné, který datový typ je v daném místě vhodný, použije se konkrétní datový typ, tedy datum či datum a čas. Často ale při tvorbě OFN není předem známo, jaká úroveň detailu bude pro určení okamžiku k dispozici. Aby se zabránilo různým reprezentacím této situace v různých OFN, je specifikována třída Časový okamžik.

Datum

Vlastnost: datum
Typ: Datum
Jméno: Datum okamžiku.
Příklad: 2019-01-01+01:00

Datum a čas

Vlastnost: datum_a_čas
Typ: Datum a čas
Jméno: Datum a čas začátku okamžiku.
Příklad: 2019-01-01T09:30:00+02:00

Nespecifikovaný okamžik

Vlastnost: nespecifikovaný
Typ: Booleovská hodnota - Ano či ne
Jméno: Nespecifikovaný časový okamžik
Popis: Nespecifikovaný časový okamžik, u kterého se ví, že jeho hodnota je neznámá. Jedná se o pro interoperabilitu výrazně lepší variantu, než si neznámou hodnotou uměle stanovit na 3333-03-03 či 9999-09-09 apod. nebo hodnotu vynechat.
Příklad: true

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/časový-okamžik.jsonld",
    "typ": "Časový okamžik",
    "datum": "2019-07-31"
}

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/časový-okamžik.jsonld",
    "typ": "Časový okamžik",
    "nespecifikovaný": true
}

datum_a_čas
2019-01-01T09:30:10.5+01:00

V datovém formátu RDF se pro specifikaci časového okamžiku používá slovník Time Ontology [[owl-time]].

@prefix time:  <http://www.w3.org/2006/time#> .
                        
[] a time:Instant ;
    time:inXSDDateTimeStamp "2019-01-01T09:30:10.5+01:00"^^xsd:dateTimeStamp .

Pokud je časový okamžik vždy určen datem a časem, pak je třeba použít vlastnosti s datovým typem Datum a čas, nikoliv dvojici vlastností kde je datum a čas odděleně.

Časový interval

Pro reprezentaci časových intervalů je potřeba buď uvést jejich začátek a konec, a nebo pouze jeden údaj, pokud ten druhý není znám, ale je známo, že se jedná o interval. Časový interval začíná a končí časovým okamžikem.

Začátek

Vlastnost: začátek
Typ: Časový okamžik
Jméno: Okamžik začátku intervalu.

Konec

Vlastnost: konec
Typ: Časový okamžik
Jméno: Okamžik konce intervalu.

JSON-LD soubor, JSON Schema, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/časový-interval.jsonld",
    "typ": "Časový interval",
    "začátek": {
        "typ": "Časový okamžik",
        "datum": "2019-07-31"
    },
    "konec": {
        "typ": "Časový okamžik",
        "datum": "2020-07-31"
    }
}

JSON-LD soubor, JSON Schema, JSON-LD kontext

Takto lze reprezentovat interval, u kterého nevíme, kdy bude končit, nicméně víme, že někdy končit bude. Jedná se o pro interoperabilitu výrazně lepší variantu, než si konec uměle definovat na 3333-03-03 či 9999-09-09 apod.

{
    "@context": "https://ofn.gov.cz/základní-datové-typy/2020-07-01/kontexty/časový-interval.jsonld",
    "typ": "Časový interval",
    "začátek": {
        "typ": "Časový okamžik",
        "datum": "2019-07-31"
    },
    "konec": {
        "typ": "Časový okamžik",
        "nespecifikovaný": true
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<interval>
    <začátek>
        <datum>2019-08-01</datum>
    </začátek>
    <konec>
        <datum>2020-08-01</datum>
    </konec>
</interval>

začátek_datum_a_čas,konec_datum_a_čas
2019-01-01T09:30:10.5+01:00,2020-01-01T09:30:10.5+01:00

V datovém formátu RDF se pro specifikaci časového intervalu používá slovník Time Ontology [[owl-time]].

@prefix time: <http://www.w3.org/2006/time#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

[] a time:ProperInterval ;
    time:hasBeginning [ a time:Instant ;
            time:inXSDDate "2019-07-31"^^xsd:date ] ;
    time:hasEnd [ a time:Instant ;
            time:inXSDDate "2020-08-01"^^xsd:date ] .