Аннотации и комментарии

Аннотации описывают схему для людей и инструментов (генераторов документации, форм, кода) и не влияют на результат проверки.

Ключевое слово	Назначение
title	Короткое название
description	Подробное описание
default	Значение по умолчанию. Валидатор его не подставляет — это подсказка для приложений
examples	Список примеров значений
deprecated	true — поле устарело и может исчезнуть
readOnly	Значение задаёт сервер; клиент не должен его присылать (например, id, createdAt)
writeOnly	Значение только отправляется и никогда не возвращается (например, пароль)
$comment	Комментарий для разработчиков схемы; не показывается пользователям

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Пользователь",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "login": {
      "title": "Логин",
      "description": "Латинские буквы, цифры и точка",
      "type": "string",
      "pattern": "^[a-z0-9.]+$",
      "examples": ["ivan.petrov"]
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "writeOnly": true
    },
    "locale": {
      "type": "string",
      "default": "ru"
    },
    "nickname": {
      "type": "string",
      "deprecated": true,
      "$comment": "Удалить после перехода мобильного приложения на login"
    }
  }
}

JSON не поддерживает комментарии в тексте. Всё, что нужно пояснить в схеме, размещайте в description или $comment.