JSON-LD a Schema.org: strukturovaná data

K čemu je JSON-LD: od objektu ke grafu

Dva systémy mohou mít klíč name, ale jeden jím označuje člověka a druhý název souboru. JSON samotný význam klíče neurčuje. JSON-LD jej sváže s IRI, například https://schema.org/name. IRI je mezinárodní identifikátor zdroje; nemusí být adresa souboru, který se má stáhnout. URI namespace v XML řeší podobný problém jednoznačného pojmenování, ale datové modely nejsou stejné.

Graf si představ jako uzly a pojmenované vztahy: Eva pracuje pro knihovnu. Uzel může mít vlastní identifikátor; hodnota „Eva“ je text, nikoli další osoba. JSON-LD je způsob zápisu takových informací, ne databáze ani pravidlo pro povinná pole. Pro běžná data interního API může stačit JSON s popisem polí a JSON Schema pro jejich kontrolu.

První příklad: osoba a její zaměstnavatel

osoba.jsonld — celý dokument

{
  "@context": {
    "@vocab": "https://schema.org/",
    "worksFor": {
      "@type": "@id"
    }
  },
  "@id": "https://example.cz/lide/eva",
  "@type": "Person",
  "name": "Eva",
  "worksFor": "https://example.cz/organizace/knihovna"
}

@context vysvětluje názvy a způsob interpretace hodnot. @vocab zde poskytuje základ pro vlastnosti a typy: name znamená Schema.org name a Person Schema.org Person. @id určuje identitu Evy. @type říká, jaký druh zdroje popisujeme; není to typ JavaScript objektu.

Definice worksFor s @type: "@id" znamená, že hodnota je identifikátor jiného uzlu. Bez tohoto pravidla by stejná adresa mohla být pouze text. Identifikátor knihovny lze použít v dalším dokumentu a oba popisy tak spojit. Přítomnost @id nezaručuje pravdivost dat ani vlastnictví adresy.

Rozvinutí: co procesor skutečně přečte

Očekávaný výsledek expand

[
  {
    "@id": "https://example.cz/lide/eva",
    "@type": [
      "https://schema.org/Person"
    ],
    "https://schema.org/name": [
      {
        "@value": "Eva"
      }
    ],
    "https://schema.org/worksFor": [
      {
        "@id": "https://example.cz/organizace/knihovna"
      }
    ]
  }
]

Rozvinutí odstraní závislost na krátkých názvech: vlastnosti a typy jsou plné IRI, text má obálku @value a vztah obálku @id. Pořadí klíčů ve výstupu nemusí být stejné. Nejde o přejmenování JSON regexem: procesor pracuje s kontextem a odlišuje identifikátory od hodnot.

Vlož celý první dokument do JSON-LD Playground.
Zobraz Expanded a porovnej identifikátor osoby, typ a vztah zaměstnavatele s výstupem výše.
Odstraň typování worksFor z kontextu. V Expanded se u zaměstnavatele změní @id na @value. JSON syntaxe přitom zůstane platná.
Zobraz RDF reprezentaci: vztah má jako objekt identifikátor knihovny, jméno textovou hodnotu.

Compaction zkracuje názvy pomocí zvoleného kontextu. Flattening shromáždí uzly grafu do seznamu a framing vybere a uspořádá informace podle zadaného vzoru. Tyto operace mění podobu zápisu; neověřují, zda data obsahují všechna pole požadovaná aplikací.

Více jazyků, seznamy a několik uzlů

Jazykové označení textových hodnot

{
  "@context": {
    "@vocab": "https://schema.org/"
  },
  "@id": "https://example.cz/knihy/xml",
  "@type": "Book",
  "name": [
    {
      "@value": "Příručka XML",
      "@language": "cs"
    },
    {
      "@value": "XML Handbook",
      "@language": "en"
    }
  ]
}

@language určuje jazyk konkrétního textu. Pokud všechny texty používají stejný jazyk, lze výchozí jazyk nastavit kontextem; jednotlivé hodnoty jej mohou přepsat. Číslo či boolean nejsou jazykově označený text.

Běžné pole hodnot JSON-LD samo nezaručuje jejich významové pořadí. Pro uspořádanou posloupnost se používá @list, například kroky postupu. Více souvisejících uzlů můžeš uvést v @graph. Identifikátor grafu je další rozhodnutí datového modelu; @graph nepoužívej jen jako náhradu každého JSON pole.

Vložení strukturovaných dat do HTML

Celá stránka; JSON-LD odpovídá viditelnému obsahu

<!doctype html>
<html lang="cs">
<head>
  <meta charset="UTF-8">
  <title>Eva — knihovnice</title>
  <script type="application/ld+json">
{
  "@context": {
    "@vocab": "https://schema.org/",
    "worksFor": {
      "@type": "@id"
    }
  },
  "@id": "https://example.cz/lide/eva",
  "@type": "Person",
  "name": "Eva",
  "worksFor": "https://example.cz/organizace/knihovna"
}
  </script>
</head>
<body><h1>Eva</h1><p>Eva pracuje v knihovně.</p></body>
</html>

Typ application/ld+json označuje datový blok. Prohlížeč tento obsah nespouští jako JavaScript. JSON-LD zde popisuje obsah stránky; nenahrazuje HTML, přístupnost ani běžné odkazy. Schema.org je slovník, JSON-LD jeho možný zápis a podpora vyhledávače další samostatná vrstva.

Při serverovém generování použij JSON serializátor a bezpečný způsob vložení do HTML. Řetězec obsahující zakončení script nesmí předčasně uzavřít element; při vložení JSON do HTML lze znak menší než zapisovat Unicode escape sekvencí. Pouhé HTML escapování JSON může změnit data. Ukázka výše obsahuje jen pevné důvěryhodné hodnoty.

Jak validovat a hledat chyby

Nejdřív ověř JSON syntax v JSON validátoru. Potom dokument zpracuj JSON-LD procesorem a zkontroluj rozvinutý význam. Nakonec ověř požadavky slovníku a cílové aplikace. Platný JSON, úspěšné rozvinutí a přijetí dat vyhledávačem jsou různé výsledky.

Klíč mimo kontext nemusí vytvořit očekávanou vlastnost grafu. Zkontroluj Expanded, ne pouze zelený JSON validátor.
Krátký typ bez vhodného kontextu nemusí označovat očekávané IRI. Prefix či @vocab zapiš výslovně.
Opakované použití stejného @id spojuje popisy jednoho zdroje; pro různé osoby vyber různé identity.
Vzdálený kontext může vyžadovat síťový přístup. Pro reprodukovatelný serverový proces omez document loader, používej cache a připnuté kontexty.

Verze a další studium

JSON-LD 1.1 je W3C Recommendation z 16. července 2020. Syntax popisuje JSON-LD 1.1, operace Processing Algorithms and API. Konkrétní procesor musí podporovat použitý režim a vlastnosti. HTTP reprezentace používá application/ld+json.

Pokračuj datovou validací JSON Schema, přenosem přes HTTP a bezpečným zpracováním JSON. JSON-LD neposkytuje šifrování, podpis ani autorizaci.