Kontakty

Abstrakt

Tento dokument je sdílenou specifikací pro kontakty pro použití v otevřeý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]] a CSV [[rfc4180]]. Ukazuje, jak reprezentovat informace o telefonních číslech, e-mailových adresách a odkazech na webové stránky.

Specifikace

V této sekci jsou definovány vlastnosti kontaktu. Pro každou vlastnost je uveden její identifikátor, který je pro její reprezentaci použit ve všech datových formátech, její název, datový typ, popis a příklad. Všechny třídy, které nejsou specifikovány jinou otevřenou formální normou nebo číselníkem, dědí vlastnosti a vazby třídy Věc.

Kontakt

Kontakt na člověka či společnost. Kromě níže specifikovaných vlastností a vazeb je možné u této třídy použít také vlastnosti a vazby třídy Věc, která je specifikována otevřenou formální normou Věc.

Druh kontaktu

Vlastnost: druh
Typ: Text
Jméno: Druh kontaktu
Popis: Druh kontaktu, například Oficiální, Neformální, apod.
Příklad: Neformální

E-mail

Vlastnost: email
Typ: URL dle [[!rfc6068]].
Jméno: E-mail
Popis: Kontaktní e-mailová adresa
Příklad: mailto:otevrenadata@dia.gov.cz

Facebook

Vlastnost: facebook
Typ: Řetězec
Jméno: Účet na Facebooku
Popis: Uživatelské jméno na Facebooku.
Příklad: MinisterstvoobranyCeskerepubliky

ID datové schránky

Vlastnost: idds
Typ: Řetězec
Jméno: ID datové schránky
Popis: ID datové schránky.
Příklad: abcdef

Instagram

Vlastnost: instagram
Typ: Řetězec
Jméno: Účet na Instagramu
Popis: Uživatelské jméno na Instagramu.
Příklad: ceskystatistickyurad

Kontaktní URL

Vlastnost: url
Typ: URL
Jméno: Adresa na webu
Popis: Webová kontaktní adresa: webová stránka či WebID.
Příklad: https://data.gov.cz/

Mobilní telefon

Vlastnost: mobil
Typ: URL dle [[!rfc3966]].
Jméno: Mobilní telefon
Popis: Telefonní číslo na mobilní telefon.
Příklad: tel:+420123456789

Telefon

Vlastnost: telefon
Typ: URL dle [[!rfc3966]].
Jméno: Telefon
Popis: Telefonní číslo na pevnou linku.
Příklad: tel:+420123456789

Twitter

Vlastnost: twitter
Typ: Řetězec
Jméno: Účet na Twitteru
Popis: Uživatelské jméno na Twitteru.
Příklad: vnitro

Vazba: Umístění

Vazba: umístění
Typ: Umístění
Jméno: Kontaktní místo
Popis: Místo, na kterém lze subjekt kontaktovat.

Příklady

V této sekci jsou uvedeny příklady reprezentace kontaktů ve formátech JSON-LD [[!json-ld11]] a tedy i JSON [[!ECMA-404]], XML [[!xml]] a CSV [[!rfc4180]] a v různých úrovních detailu. Datová schémata, která jsou použita v příkladech, lze přímo použít a zahrnout do publikačních plánů. Pro formáty JSON a XML jsou k dispozici příslušná schémata, tedy Schéma pro formát JSON v jazyce JSON Schema [[!json-schema]] a Schéma pro formát XML v jazyce XML Schema [[!xmlschema11-1]]. Pro formát JSON-LD [[!json-ld11]] je k dispozici kontext. Lze také použít zápis v CSV. Soubor v CSV je nutné doplnit schématem dle specifikace CSV on the Web [[!tabular-data-primer]].

Pokud je kontakt použit v rámci jiného datového standardu, tak se jména sloupců v CSV tabulce tvoří názvy atributů. Zanořování je řešeno spojením názvu entity z jiného standardu, například kontaktní_osoba a z názvu atributu kontaktu jejich spojením pomocí znaku podtržítka _, například kontaktní_osoba_email.

Kontaktní telefon a e-mail

JSON-LD soubor, JSON Schema, JSON Schema pro více kontaktů, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/kontakty/2020-07-01/kontexty/kontakt.jsonld",
    "typ": "Kontakt",
    "telefon": "tel:+420123456789",
    "email": "mailto:otevrenadata@dia.gov.cz"
}

V XML musí být atributy seřazeny dle specifikace. V případě kontaktu je to dle abecedy:

XML soubor

<?xml version="1.0" encoding="UTF-8"?>
<kontakt:kontakt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:kontakt="https://ofn.gov.cz/kontakty/2020-07-01" 
xsi:schemaLocation="https://ofn.gov.cz/kontakty/2020-07-01 https://ofn.gov.cz/kontakty/2020-07-01/schémata/kontakt.xsd">
    <kontakt:email>mailto:otevrenadata@dia.gov.cz</kontakt:email>
    <kontakt:telefon>tel:+420123456789</kontakt:telefon>
</kontakt:kontakt>

CSV soubor

email,telefon
mailto:otevrenadata@dia.gov.cz,tel:+420123456789

K souboru CSV je třeba připojit metadata dle standardu CSV on the Web [[tabular-data-primer]]. Například pokud se CSV soubor jmenuje kontakt.csv, je s ním publikován i metadatový soubor kontakt.csv-metadata.json:

Deskriptor

{
    "@id": "https://ofn.gov.cz/kontakty/2020-07-01/příklady/1.csv-metadata.json",
    "@context": [
        "http://www.w3.org/ns/csvw",
        {"@language": "cs"}
    ],
    "@type": "Table",
    "url": "1.csv",
    "tableSchema": {
        "@type": "Schema",
        "columns": [
            {
                "@type": "Column",
                "name": "email",
                "titles": "email",
                "propertyUrl": "vcard:hasEmail",
                "valueUrl": "{+email}",
                "dc:description": "Kontaktní e-mailová adresa",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "telefon",
                "titles": "telefon",
                "propertyUrl": "vcard:hasTelephone",
                "valueUrl": "{+telefon}",
                "dc:description": "Telefonní číslo na pevnou linku",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "virtual": true,
                "propertyUrl": "rdf:type",
                "valueUrl": "vcard:VCard"
            }
        ]
    }
}

Jednoduchý kontakt s přidaným vlastním atributem

Do schématu si lze v případě potřeby přidávat další atributy. V následujících příkladech jsou nad rámec standardu přidán atribut telegram.

JSON-LD soubor, JSON Schema, JSON Schema pro více kontaktů, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/kontakty/2020-07-01/kontexty/kontakt.jsonld",
    "typ": "Kontakt",
    "telefon": "tel:+420123456789",
    "email": "mailto:otevrenadata@dia.gov.cz",
    "telegram": "jakub_klimek"
}

V XML lze vlastní atributy přidat na začátek, do elementu <základ:rozšiřující_položky>, do vlastního XML jmenného prostoru (XML namespace [[!xml-names]]). V tomto příkladu jsou nové atributy přidány do XML jmenného prostoru x.

XML soubor:

<?xml version="1.0" encoding="UTF-8"?>
<kontakt:kontakt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:kontakt="https://ofn.gov.cz/kontakty/2020-07-01"
xmlns:základ="https://ofn.gov.cz/základní-datové-typy/2020-07-01" 
xmlns:x="https://příklad.cz"
xsi:schemaLocation="https://ofn.gov.cz/kontakty/2020-07-01 https://ofn.gov.cz/kontakty/2020-07-01/schémata/kontakt.xsd">
    <základ:rozšiřující_položky>
        <x:telegram>jakub_klimek</x:telegram>
    </základ:rozšiřující_položky>
    <kontakt:email>mailto:otevrenadata@dia.gov.cz</kontakt:email>
    <kontakt:telefon>tel:+420123456789</kontakt:telefon>
</kontakt:kontakt>

Alternativně je možné si nadefinovat celé nové XML schéma, které by vycházelo ze zde uvedeného základního XML schématu.

CSV soubor

email,telefon,telegram
mailto:otevrenadata@dia.gov.cz,tel:+420123456789,jakub_klimek

K souboru CSV je opět potřeba připojit metadatový popsiek dle standardu CSV on the Web [[!tabular-data-primer]]:

Deskriptor

{
    "@id": "https://ofn.gov.cz/kontakty/2020-07-01/příklady/2.csv-metadata.json",
    "@context": [
        "http://www.w3.org/ns/csvw",
        {"@language": "cs"}
    ],
    "@type": "Table",
    "url": "2.csv",
    "header": true,
    "tableSchema": {
        "@type": "Schema",
        "columns": [
            {
                "@type": "Column",
                "name": "email",
                "titles": "email",
                "propertyUrl": "vcard:hasEmail",
                "valueUrl": "{+email}",
                "dc:description": "Kontaktní e-mailová adresa",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "telefon",
                "titles": "telefon",
                "propertyUrl": "vcard:hasTelephone",
                "valueUrl": "{+telefon}",
                "dc:description": "Telefonní číslo na pevnou linku",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "telegram",
                "titles": "telegram",
                "dc:description": "Uživatelské jméno na telegramu",
                "datatype": "string"
            }, {
                "@type": "Column",
                "virtual": true,
                "propertyUrl": "rdf:type",
                "valueUrl": "vcard:VCard"
            }
        ]
    }
}

Komplexní kontakt

Kontakty mohou obsahovat různé množství informací. Některé mohou být detailní.

JSON-LD soubor, JSON Schema, JSON Schema pro více kontaktů, JSON-LD kontext

{
    "@context": "https://ofn.gov.cz/kontakty/2020-07-01/kontexty/kontakt.jsonld",
    "typ": "Kontakt",
    "druh": {
        "cs": "Neformální",
        "en": "Informal"
    },
    "email": "mailto:otevrenadata@dia.gov.cz",
    "idds": "abcdef",
    "mobil": "tel:+420123456789",
    "telefon": "tel:+420123456789",
    "url": "https://data.gov.cz",
    "umístění": {
        "typ": "Umístění",
        "adresa": {
            "typ": "Adresa",
            "adresní_místo": "https://linked.cuzk.cz/resource/ruian/adresni-misto/16135661"
        }
    }
}

XML soubor

<?xml version="1.0" encoding="UTF-8"?>
<kontakt:kontakt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:kontakt="https://ofn.gov.cz/kontakty/2020-07-01"
xmlns:x="https://příklad.cz"
xmlns:adresy="https://ofn.gov.cz/adresy/2020-07-01"
xmlns:umístění="https://ofn.gov.cz/umístění/2020-07-01"
xsi:schemaLocation="https://ofn.gov.cz/kontakty/2020-07-01 https://ofn.gov.cz/kontakty/2020-07-01/schémata/kontakt.xsd">
    <kontakt:druh xml:lang="cs">Neformální</kontakt:druh>
    <kontakt:druh xml:lang="en">Informal</kontakt:druh>
    <kontakt:email>mailto:otevrenadata@dia.gov.cz</kontakt:email>
    <kontakt:idds>abcdef</kontakt:idds>
    <kontakt:mobil>tel:+420123456789</kontakt:mobil>
    <kontakt:telefon>tel:+420123456789</kontakt:telefon>
    <kontakt:url>https://data.gov.cz</kontakt:url>
    <kontakt:umístění>
        <umístění:adresa>
            <adresy:adresní_místo>https://linked.cuzk.cz/resource/ruian/adresni-misto/16135661</adresy:adresní_místo>
        </umístění:adresa>
    </kontakt:umístění> 
</kontakt:kontakt>

CSV soubor

druh_cs,druh_en,email,idds,mobil,telefon,url,umístětní_adresa_adresní_místo
Neformální,Informal,mailto:otevrenadata@dia.gov.cz,abcdef,tel:+420123456789,tel:+420123456789,https://data.gov.cz,https://linked.cuzk.cz/resource/ruian/adresni-misto/16135661

A opět je k souboru CSV potřeba připojit metadatový popisek dle standardu CSV on the Web [[!tabular-data-primer]]:

Deskriptor

{
    "@id": "https://ofn.gov.cz/kontakty/2020-07-01/příklady/3.csv-metadata.json",
    "@context": [
        "http://www.w3.org/ns/csvw",
        {"@language": "cs"}
    ],
    "@type": "Table",
    "url": "3.csv",
    "tableSchema": {
        "@type": "Schema",
        "columns": [
            {
                "@type": "Column",
                "name": "druh_cs",
                "titles": "druh_cs",
                "propertyUrl": "https://slovník.gov.cz/generický/kontakty/pojem/druh",
                "dc:description": "Druh kontaktu (česky)",
                "datatype": "string",
                "lang": "cs"
            }, {
                "@type": "Column",
                "name": "druh_en",
                "titles": "druh_en",
                "propertyUrl": "https://slovník.gov.cz/generický/kontakty/pojem/druh",
                "dc:description": "Druh kontaktu (anglicky)",
                "datatype": "string",
                "lang": "en"
            }, {
                "@type": "Column",
                "name": "email",
                "titles": "email",
                "propertyUrl": "vcard:hasEmail",
                "valueUrl": "{+email}",
                "dc:description": "Kontaktní e-mailová adresa",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "idds",
                "titles": "idds",
                "propertyUrl": "https://slovník.gov.cz/generický/kontakty/pojem/má-datovou-schránku",
                "dc:description": "ID datové schránky",
                "datatype": "string"
            }, {
                "@type": "Column",
                "name": "mobil",
                "titles": "mobil",
                "propertyUrl": "vcard:hasTelephone",
                "valueUrl": "{+mobil}",
                "dc:description": "Telefonní číslo na mobilní telefon.",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "telefon",
                "titles": "telefon",
                "propertyUrl": "vcard:hasTelephone",
                "valueUrl": "{+telefon}",
                "dc:description": "Telefonní číslo na pevnou linku",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "url",
                "titles": "url",
                "propertyUrl": "vcard:hasURL",
                "valueUrl": "{+url}",
                "dc:description": "Adresa webové stránky pro kontakt",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "name": "umistetni_adresa_adresni_misto",
                "titles": "umístětní_adresa_adresní_místo",
                "propertyUrl": "http://www.w3.org/ns/locn#address",
                "dc:description": "Adresa pro kontakt",
                "datatype": "anyURI"
            }, {
                "@type": "Column",
                "virtual": true,
                "propertyUrl": "rdf:type",
                "valueUrl": "vcard:VCard"
            }, {
                "@type": "Column",
                "virtual": true,
                "propertyUrl": "rdf:type",
                "valueUrl": "dcterms:Location"
            }
        ]
    }
}

Abstrakt

Přehled

Specifikace

Kontakt

Druh kontaktu

E-mail

Facebook

ID datové schránky

Instagram

Kontaktní URL

Mobilní telefon

Telefon

Twitter

Vazba: Umístění

Příklady

Kontaktní telefon a e-mail

Jednoduchý kontakt s přidaným vlastním atributem

Komplexní kontakt