Summary of JSON: Data Interchange and Schema

## Úvod JSON Schema je jazyk pro popis struktury JSON dokumentů a jejich validaci. Umožňuje definovat očekávané typy hodnot, povinné položky, rozsahy čísel, formáty řetězců a vztahy mezi částmi dokumentu. Tento materiál vysvětluje klíčové koncepty JSON Schema (draft 2020-12) s praktickými příklady a poznámkami pro použití ve skutečných projektech. > Definice: JSON Schema je formální specifikace pro popis, validaci a dokumentaci struktury JSON dokumentů. ## Základní principy ### Deklarace schématu a identifikace - Každé schéma může začínat deklarací verze: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` - Volitelně lze nastavit identifikátor: "$id": "http://example.com/schemas/myschema.json". Pokud není uveden, jde o anonymní schéma. ### Anotace a komentáře - Vlastnosti jako **title**, **description** a **$comment** slouží k dokumentaci a nejsou validačními pravidly. > Definice: Anotace jsou popisné pole ve schématu (např. title, description), která pomáhají porozumět datům, ale neovlivňují validaci. ## Datové typy a omezení JSON Schema staví na nativních JSON typech: object, array, string, number, integer, boolean, null. ### Čísla a celá čísla - Typy: **integer**, **number**. - Omezení: **multipleOf**, **minimum**, **exclusiveMinimum**, **maximum**, **exclusiveMaximum**. Příklad: hodnota musí být násobkem 10 a větší nebo rovna 0 ```json { "type": "number", "multipleOf": 10, "minimum": 0 } ``` ### Řetězce - Omezení: **minLength**, **maxLength**, **pattern** (RegExp podle ECMA-262), **format** (např. date-time, email, uri, uuid). Příklad: e-mail a délka ```json { "type": "string", "format": "email", "maxLength": 254 } ``` ### Boolean a null - **type": "boolean"** pro true/false - **type": "null"** reprezentuje explicitně hodnotu null (není chybějící hodnota) ### Enum - Definice konkrétních povolených hodnot: **enum**: ["red","amber","green"] ## Práce s objekty ### Základní definice objektu - Typ: **type: "object"** - Vnitřní vlastnosti definujeme pomocí **properties**. - Ve výchozím stavu jsou vlastnosti, které nejsou uvedeny v properties, povoleny. Příklad: ```json { "type": "object", "properties": { "productId": { "type": "integer" }, "productName": { "type": "string" } }, "required": ["productId"] } ``` > Definice: required je pole názvů vlastností, které musí být přítomné v objektu, pokud se validace provádí. ### additionalProperties a patternProperties - **additionalProperties**: true/false nebo objekt schématu. Ve výchozím stavu je true (povolit nepopsané vlastnosti). - Např. `"additionalProperties": { "type": "string" }` povolí další vlastnosti, ale musí být řetězce. - **patternProperties**: mapuje regulární výrazy na schémata pro názvy vlastností. - Příklad: `"patternProperties": { "^S_": { "type": "string" } }` aplikuje pravidlo na všechny vlastnosti začínající na S_. ### propertyNames a omezení počtu - **propertyNames** umožňuje validovat samotná jména vlastností pomocí patternu, např. `"pattern": "^[A-Za-z0-9]*$"`. - **minProperties**, **maxProperties** definují povolený počet vlastností v objektu. ### Unevaluated properties - **unevaluatedProperties** funguje podobně jako additionalProperties, ale zapadá do situací při skládání schémat (rozšíření uzavřených schémat). Používá se při kombinacích, kde už byly některé vlastnosti vyhodnoceny jinými subschématy. Tabulka: porovnání vlastností pro neočekávané klíče | Klíč | Chování | Poznámka | |---|---:|---| | additionalProperties | Povolit/zakázat nebo definovat schéma | Aplikuje se na nevyjmenované vlastnosti | | patternProperties | Podmíněné podle názvu (RegExp) | Řízeno jménem vlastnosti | | unevaluatedProperties | Aplikuje se po vyhodnocení subschémat | Užitečné při composition | ## Pole (arrays) ### Základní vlastnosti - **type: "array"**, **items** definuje, jaká jsou očekávaná data v položkách. - Pokud **items** je jedno schéma, pak všechny položky musí odpovídat tomuto schématu. - Délka pole: *