JSON Schema: klíčová slova a příklady

Typy, čísla a řetězce

integer přijme i matematicky celé číslo zapsané jako 1.0. Číselná klíčová slova sama nevyžadují číslo, řetězcová sama nevyžadují řetězec: přidej type. enum může obsahovat také objekty, pole a null.

Samotné uvedení format nezaručuje, že každý validátor formát hodnoty zkontroluje. Ověř nastavení a podporované formáty svého validátoru. Schéma s format: "email" samo nezaručuje existenci adresy.

Objekty: přítomnost a další vlastnosti

properties validuje pojmenované vlastnosti, pokud existují. required vyžaduje jejich přítomnost, nikoli nenulovou hodnotu. Další vlastnosti jsou výchozím nastavením povolené; additionalProperties je kontroluje podle deklarací ve stejném dílčím schématu. unevaluatedProperties zohlední také úspěšně vyhodnocené části při skládání.

{"type":"object","properties":{"kod":{"type":"string"}},"required":["kod"],"additionalProperties":false}

{"kod":null} neprojde. Chybějící kód také neprojde. Pokud chceš null dovolit, použij "type":["string","null"]. Pro počet vlastností existují minProperties a maxProperties.

Seznam a n-tice: items vs prefixItems

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "items": {
    "type": "integer",
    "minimum": 0
  },
  "minItems": 1,
  "maxItems": 3,
  "uniqueItems": true
}

Zde items kontroluje všechny položky. uniqueItems porovnává celé hodnoty; není to kontrola jedinečnosti vybrané vlastnosti objektů.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "prefixItems": [
    {
      "type": "string"
    },
    {
      "type": "integer",
      "minimum": 0
    }
  ],
  "items": false,
  "minItems": 2
}

prefixItems kontroluje jednotlivé pozice. items: false zakáže položky za popsaným prefixem, ale nevyžaduje jeho úplnost. Proto je v příkladu také minItems: 2. Pole ["Jana",20] projde, jedno nebo tři políčka ne.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "items": {
    "type": "integer"
  },
  "contains": {
    "minimum": 10
  },
  "minContains": 1,
  "maxContains": 2
}

contains hledá položky odpovídající schématu, minContains a maxContains určují jejich počet. Bez upraveného minima musí odpovídat alespoň jedna položka.

Podmínky if / then / else

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "druh": {
      "enum": [
        "osoba",
        "firma"
      ]
    },
    "ico": {
      "type": "string",
      "pattern": "^[0-9]{8}$"
    }
  },
  "required": [
    "druh"
  ],
  "if": {
    "properties": {
      "druh": {
        "const": "firma"
      }
    },
    "required": [
      "druh"
    ]
  },
  "then": {
    "required": [
      "ico"
    ]
  },
  "else": {
    "not": {
      "required": [
        "ico"
      ]
    }
  },
  "additionalProperties": false
}

if vybírá větev, samo nevytváří validační chybu. Pokud chybí required uvnitř podmínky, properties může uspět i bez vlastnosti. Kontrola osmi číslic ověřuje formát IČO, nikoli jeho existenci nebo kontrolní součet.

Časté chyby a doporučení

• default popisuje výchozí hodnotu; standardní validace ji sama do dat nevloží.
• Neuzavírej opakovaně použitelný základ dřív, než přidáš další vlastnosti.
• Příklad, který projde, nestačí: otestuj i chybějící hodnotu, chybný typ a vlastnost navíc.
• Nemíchej klíčová slova různých dialektů; uvedení $schema nestačí bez podpory knihovny.

Logické kombinace allOf, anyOf, oneOf a not vysvětluje další kapitola. Všechna klíčová slova v jedné tabulce má reference JSON Schema a tahák XML a JSON.

Objekt: závislosti, názvy a chybějící hodnoty

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "minLength": 1
    },
    "souhlas": {
      "const": true
    }
  },
  "dependentRequired": {
    "email": [
      "souhlas"
    ]
  },
  "additionalProperties": false
}

{} projde, protože email není povinný. {"email":"eva@example.cz"} neprojde: chybí souhlas. {"email":"eva@example.cz","souhlas":true} projde. dependentRequired reaguje na přítomnost vlastnosti, nikoli na její neprázdnost. Samostatné const: true zakazuje false, ale přítomnost nezaručuje.

dependentSchemas aplikuje při přítomnosti klíče schéma na celý objekt. propertyNames kontroluje názvy, například zakázané mezery, a patternProperties vybírá vlastnosti podle regexu. Pokud název odpovídá více vzorům, musejí projít všechny odpovídající podmínky. Tyto konstrukce jsou jiné než properties pro pevně známé názvy.

Pravidla pro čísla, výčet hodnot a text

{
  "type": "object",
  "required": [
    "stav",
    "pocet",
    "kod"
  ],
  "properties": {
    "stav": {
      "enum": [
        "novy",
        "odeslany"
      ]
    },
    "pocet": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "kod": {
      "type": "string",
      "pattern": "^[A-Z]{2}[0-9]{3}$"
    }
  },
  "additionalProperties": false
}

{"stav":"novy","pocet":2,"kod":"CZ001"}

Změna stavu na hotovy poruší enum, počtu na 0 minimum a kódu na CZ1 pattern. Regex je ukotvený, aby nesměl odpovídat jen část řetězce. minimum a maximum zahrnují hranici; exclusive varianty ji vylučují. multipleOf kontroluje násobek, ale praktické knihovny mohou vyžadovat pozornost u desetinné aritmetiky. U peněžních částek určete s příjemcem způsob zápisu a požadovanou přesnost.

Klíčová slova obvykle působí jen na příslušný typ: minimum: 1 samo neodmítne řetězec. Typ proto uváděj výslovně. format nepoužívej jako jediný důkaz existence adresy ani pravosti data.

Popisné údaje a schémata true/false

{"type":"string","title":"Název","description":"Viditelné jméno knihy","default":"Bez názvu","examples":["XML"]}

title, description, default a examples dokumentují data. Standardní validace default nedoplňuje. Pole examples není enum. readOnly a writeOnly popisují pole určená pro čtení nebo zápis. Aplikace musí sama vynucovat, co klient smí poslat a co server smí vrátit; tyto značky samy nekontrolují oprávnění.

Schéma může být i logická hodnota JSON: true přijme jakákoli data, false žádná. Prázdné objektové schéma přijme také vše. To se hodí pro zákaz dodatečných položek, ale při překlepu ve vlastním pravidle může schéma přijímající i nežádoucí data zůstat platné. Ověř schéma proti jeho meta schématu a připrav negativní test.

Přesná pravidla specifikace jsou v Validation 2020-12; odkazy a dialekty v Core.