{"canonical_url":"https://engineer.company/uk/glossary/json-schema/","content_markdown":"# JSON Schema\n\n## Що це таке\n\nJSON Schema — це мова для опису того, яким має бути фрагмент JSON, і пишуть цією\nмовою теж у JSON. Опис нею, який називають схемою, задає правила: це значення —\nоб'єкт, у нього мають бути такі властивості, ця властивість — ціле число, не\nменше за одиницю, а та — рядок щонайбільше з 200 символів. Програма, яку\nназивають валідатором, бере схему й екземпляр, тобто дані, які перевіряють, і\nвідповідає, чи екземпляр відповідає схемі, а якщо ні, то де саме і чому. Проєкт\nпише свою назву з великою S, JSON Schema, а окремий документ, написаний цією\nмовою, англійською називають просто schema, з малої літери, а українською —\nсхемою.\n\nСпецифікацію підтримує проєкт JSON Schema на json-schema.org. Поточна версія —\n2020-12, попередня — 2019-09; ранніші версії мали номери чернеток, як-от\ndraft-04 і draft-07, і старіші інструменти та статті досі називають їх так.\nТекст складається з двох частин. Основний документ, Core, визначає, як\nобробляють схему, як одна схема посилається на іншу, а також медіатип\n`application/schema+json`, а другий документ, про валідацію, визначає ключові\nслова, що перевіряють значення. Чинні документи версії 2020-12 обидва датовано\n16 червня 2022 року.\n\nКожне ключове слово додає одне обмеження. `type` називає один із шести\nпримітивних типів, тобто null, boolean, object, array, number або string, чи\n`integer`, якому відповідає будь-яке число з нульовою дробовою частиною. Для\nчисел є `minimum`, `maximum` і `multipleOf`; для рядків — `minLength`,\n`maxLength` і `pattern`, регулярний вираз; для масивів — `minItems`, `maxItems`\nі `uniqueItems`; для об'єктів — `properties`, `required` і\n`additionalProperties`. Ключові слова `allOf`, `anyOf`, `oneOf` і `not`\nпоєднують схеми, а `$ref` указує на схему, визначену деінде, часто в `$defs`\nтого самого документа, тож структуру, описану один раз, можна використовувати в\nбагатьох місцях. Усе, про що схема не згадує, дозволено. Порожня схема, `{}`,\nприймає будь-який екземпляр.\n\nСхема може також указати, якою версією мови її написано. Ключове слово `$schema`\nмістить адресу метасхеми, тобто схеми, що описує правильні схеми для цієї\nверсії, і сторінка специфікації зазначає, що метасхема перевіряє сама себе. Для\n2020-12 ця адреса — `https://json-schema.org/draft/2020-12/schema`.\n\n## Чому це важливо\n\nJSON нічого не каже про зміст. Будь-який синтаксично правильний документ\nрозбирається, хоч би що з ним могла зробити програма, яка його читає. Без\nписьмового опису кожна програма, що читає документ, має власне уявлення про те,\nякі дані правильні, розкидане по умовах у її коді, і ці уявлення розходяться,\nдоки якийсь запит не впаде в робочому середовищі. Схема збирає правила в одному\nмісці, у формі, яку можуть прочитати й люди, й програми, і її можна зберігати,\nверсіонувати, рецензувати та публікувати, як будь-який інший файл.\n\nСпецифікація формулює своє призначення широко: JSON Schema призначена для\nвалідації, документування, навігації гіперпосиланнями й керування взаємодією з\nданими JSON, а словник валідації має також давати екранам, що показують ці дані,\nпідказки про них. На практиці це означає, що один опис може відхиляти хибні\nвхідні дані на межі сервісу, документувати API, будувати форму і перевіряти, що\nJSON, який повертає мовна модель, має поля, яких очікує наступний крок.\n\nJSON Schema стала й спільною основою, на якій будують інші специфікації. OpenAPI\n3.1 визначає свій Schema Object як надмножину JSON Schema 2020-12, тож тіла\nзапитів і відповідей в описі API — це JSON Schema з кількома доповненнями. MCP,\nпротокол, через який ШІ-агенти знаходять і викликають інструменти, описує\nпараметри кожного інструмента полем `inputSchema`, що є JSON Schema, і може\nописувати його результат полем `outputSchema`, за яким клієнтам слід перевіряти\nструктуровані результати. Тож спільний опис може служити валідатору, документу API та агентові.\n\n## Як це виглядає на практиці\n\nСхема нижче описує вхідні дані інструмента, який бронює слот доставки. Вона\nназиває версію, якою написана, перелічує чотири властивості з їхніми правилами,\nуказує, які три мають бути присутні, і відхиляє будь-яку властивість, якої не\nперелічено:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://example.com/tools/book-slot.json\",\n  \"title\": \"Забронювати слот доставки\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"order\": { \"type\": \"string\", \"pattern\": \"^[0-9]{4,8}$\" },\n    \"date\": { \"type\": \"string\", \"format\": \"date\" },\n    \"pallets\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 30 },\n    \"note\": { \"type\": [\"string\", \"null\"], \"maxLength\": 200 }\n  },\n  \"required\": [\"order\", \"date\", \"pallets\"],\n  \"additionalProperties\": false\n}\n```\n\nЕкземпляр, що порушує правила:\n\n```json\n{ \"order\": \"4471\", \"date\": \"27/10/2026\", \"pallets\": 0, \"pallet\": 2 }\n```\n\nЦей екземпляр не проходить із двох причин. `pallets` менше за мінімум 1, а\n`pallet`, одруківка в `pallets`, — властивість, якої схема не перелічує.\nВідсутній `note` помилкою не є, бо `note` немає в `required`; якби його\nнадіслали як `null`, це теж пройшло б, бо його тип допускає null. Найповчальніша\nтут дата. Формат `date` вимагає, щоб рік ішов першим, а `27/10/2026` записано не\nтак, проте валідатор із налаштуваннями за замовчуванням її приймає, бо\nспецифікація робить `format` анотацією, яку перевіряють, лише коли таку\nперевірку ввімкнено. Увімкніть її у валідаторі, що вміє перевіряти дати, і той\nсамий екземпляр не пройде вже з трьох причин.\n\nСаме про інструменти, описані так, ідеться на сторінці цього сайту\n[ваші програми як інструменти для ШІ-агентів](/uk/ai-tools/). Вона описує кожну\nоперацію, потрібну агентові, як-от забронювати слот чи відвантажити замовлення,\nяк інструмент із типізованими вхідними даними, помилками, на які агент може\nзреагувати, та ідемпотентними викликами, тож повторна спроба не створить другого\nбронювання. Опис — це документ OpenAPI, згенерований із коду, а MCP-сервер надає\nті самі операції. Головна думка сторінки така: агент вірить описові інструмента,\nнавіть коли той уже застарів, а написаний вручну опис може розійтися з реалізацією. Тому описи генеруються з коду, ланцюжком від бази даних через API\nй опис до клієнта, а перевірка на кожній ланці зупиняє збірку, щойно дві з них\nрозходяться.\n\n## Де виникають проблеми\n\n**Перелічена властивість, яку ніколи не вимагають.** `properties` перевіряє лише\nті властивості, що присутні, тож об'єкт, у якому немає жодної з них, проходить.\nПрисутність задає окреме ключове слово, і якщо `required` пропустити, не\nвимагається нічого. Пишіть `required` поруч із `properties` щоразу й тримайте\nтестовий кейс для кожної обов'язкової властивості, з якого цю властивість\nвилучено.\n\n**Одруківки, що проходять як зайві властивості.** Без `additionalProperties`\nдозволено будь-яку властивість, якої схема не перелічує, тож `pallet` проходить,\nа справжньої `pallets` непомітно бракує. Значення `false` закриває об'єкт, але\nце ключове слово бачить лише `properties` і `patternProperties` у власному\nоб'єкті схеми. Схема, що будується на іншій через `allOf` чи `$ref`, а потім\nзакривається так само, відхиляє саме ті властивості, які успадкувала. У версії\n2020-12 для цього випадку є `unevaluatedProperties`, бо воно враховує й\nвластивості, перевірені через `allOf`, `$ref` та інші ключові слова, що\nзастосовують схеми на місці. Ставте `additionalProperties: false` у схемі, що\nстоїть окремо, і `unevaluatedProperties: false` у складеній.\n\n**`format`, що нічого не перевіряє.** За замовчуванням `format` — це анотація, а\nне твердження: специфікація вимагає, щоб валідатор, який уміє перевіряти\nформати, тримав цю перевірку вимкненою, доки її не попросять, і навіть коли її\nввімкнено, валідатор може пропускати будь-який формат без перевірки. OpenAPI 3.1\nдотримується того самого правила й додає, що якість перевірки форматів різниться\nміж реалізаціями. Увімкніть перевірку форматів у своєму валідаторі, доведіть це\nтестовим кейсом, який має впасти, а там, де формат важливий, але перевірити його\nне можна, додайте `pattern` або перевірку в коді.\n\n**Шаблони, що збігаються з частиною значення.** `pattern` не прив'язаний до\nпочатку й кінця значення, тож `[0-9]{4}` приймає `order 4471b`, бо чотири цифри\nтрапляються десь усередині; власний приклад специфікації — `es`, що збігається з\n`expression`. Починайте шаблон із `^` і закінчуйте `$`, коли має збігатися все\nзначення. Шаблони пишуть діалектом ECMA-262, і специфікація радить невеликий\nнабір конструкцій для шаблонів, які мають поводитися однаково скрізь, тож\nтримайтеся простих класів символів, квантифікаторів і якорів.\n\n**Відсутнє, null і порожнє вважають одним і тим самим.** Відсутня властивість,\nвластивість зі значенням `null` і порожній рядок — це три різні екземпляри.\n`\"type\": \"string\"` відхиляє `null`, а властивість, якої немає в `required`, може\nбути відсутня. Клієнт, що надсилає `null`, маючи на увазі «немає значення», до\nсхеми, написаної з розрахунку на відсутність, отримує відмову на кожному такому\nзапиті. Вирішіть для кожної властивості, що означає кожен із трьох варіантів, і\nзапишіть це: `[\"string\", \"null\"]`, коли null щось означає, відсутність у\n`required`, коли властивість необов'язкова, і `minLength: 1`, коли порожній\nрядок значенням не є.\n\n**Немає `$schema`, або змішано дві версії.** Коли в корені схеми немає\n`$schema`, специфікація залишає поведінку на розсуд реалізації, і кожен\nвалідатор застосовує ту версію, яка в нього за замовчуванням. Версії\nвідрізняються там, де це важливо. У 2019-09 масив, переданий у `items`, описував\nкортеж; у 2020-12 це робить `prefixItems`, а `items` перебрало роль\n`additionalItems`. Ставте `$schema` у кожен корінь, читайте примітки до випуску,\nколи переходите між версіями, і перевіряйте кожну схему за її метасхемою в CI.\n\n## Що почитати далі\n\n- [JSON Schema Specification](https://json-schema.org/specification) — сторінка\n  проєкту з поточною версією, її метасхемами та примітками до випуску для кожної\n  ранішої чернетки.\n- [JSON Schema: A Media Type for Describing JSON Documents](https://json-schema.org/draft/2020-12/json-schema-core)\n  — Core 2020-12: як обробляють схеми, `$schema`, `$ref` і `$defs`, а також\n  ключові слова, що поєднують схеми.\n- [JSON Schema Validation: A Vocabulary for Structural Validation of JSON](https://json-schema.org/draft/2020-12/json-schema-validation)\n  — ключові слова для кожного типу значень, `required` і правила для `format`.\n- [JSON Schema 2020-12 Release Notes](https://json-schema.org/draft/2020-12/release-notes)\n  — що змінилося з 2019-09: `prefixItems` і `$dynamicRef` поруч із тим, що вони\n  замінили.\n- [OpenAPI Specification v3.1.1](https://spec.openapis.org/oas/v3.1.1.html) —\n  Schema Object як надмножина JSON Schema 2020-12 і `format` як анотація за\n  замовчуванням.\n- [Model Context Protocol: Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)\n  — як інструмент оголошує свої параметри й структурований результат у JSON\n  Schema.\n\n\u003chttps://engineer.company/uk/glossary/json-schema/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Як документ JSON описує, якими мають бути правильні дані, де цей один опис стає в пригоді, і налаштування за замовчуванням, що пропускають хибні дані.","formats":{"gemtext":"https://engineer.company/uk/glossary/json-schema/index.gmi","gopher":"https://engineer.company/uk/glossary/json-schema/gophermap","html":"https://engineer.company/uk/glossary/json-schema/","json":"https://engineer.company/uk/glossary/json-schema/index.json","markdown":"https://engineer.company/uk/glossary/json-schema/index.md","pdf":"https://engineer.company/uk/glossary/json-schema/index.pdf"},"kind":"page","language":"uk","title":"Що таке JSON Schema?","url":"https://engineer.company/uk/glossary/json-schema/","version":1}