Инструменты разработчика · JSON форматировщик и валидатор
Действительный JSON и действительный для схемы: два значения слова «действительный»
· Фон
JSON стандарты проверка
Валидатор, утверждающий, что ваш JSON действителен, означает только то, что он анализирует. В этом посте объясняются уровни достоверности (синтаксис, структура, семантика) и почему JSON Схема существует для всего, что выходит за рамки грамматики.
Действителен, но все еще отклонен
Запрос может быть безупречным JSON и при этом быть неприемлемым для API. `{"username":"nori","plan":"gold"}` имеет сбалансированные разделители, имена в кавычках и допустимые значения, однако служба может потребовать электронное письмо, отклонить название плана или запретить создание учетной записи в текущем состоянии. Парсер и приложение отвечают на разные вопросы, поэтому оба результата могут быть правильными.
ToolAcre отвечает только на первый вопрос: можно ли проанализировать этот текст как строгий JSON в пределах его входных ограничений? Он не загружает схему, не проверяет необходимые свойства, форматы, не обращается к базе данных и не оценивает бизнес-правила. Когда инструмент сообщает «Действительно», читайте это как «правильно сформированный синтаксис JSON», а не как одобрение системы, которая будет использовать это значение.
Уровень первый: правильно сформированный синтаксис
Проверка синтаксиса проверяет грамматику JSON: одно значение верхнего уровня, правильно спаренные контейнеры, имена объектов в кавычках, допустимые запятые и двоеточия, допустимые строки, допустимые числа и точные литералы. Он отклоняет `NaN` и `Infinity`, комментарии, конечные запятые и строки в одинарных кавычках. Он принимает любую грамматически допустимую форму, включая одиночное число или объект с незнакомыми полями.
Неверный исходный код имеет текстовую точку отказа, поэтому ToolAcre может сообщить о строке и столбце для первого невозможного символа. Отсутствие запятой может привести к сообщению следующей цитаты; конечная запятая может привести к сообщению закрывающего разделителя. Исправление синтаксиса создает анализируемое значение, но не устанавливает, что это значение имеет форму или значение, ожидаемое другой программой.
Уровень второй: форма
Проверка формы спрашивает, соответствует ли проанализированное значение объявленному контракту. Пользовательская схема может потребовать `email`, ограничить `age` целым числом не ниже 18, ограничить `tier` до `free` или `pro` и запретить неизвестные свойства. `{"email":false,"tier":"gold"}` является допустимым синтаксисом JSON, но не соответствует этим структурным правилам, поскольку типы значений и разрешенные варианты выбора неверны.
JSON Схема — это один из способов выражения таких ограничений, но ToolAcre не выполняет его. Валидатор схемы обычно сообщает путь к экземпляру, например `/tier`, ключевое слово, например `enum`, и поясняющее сообщение, а не курсор синтаксического анализатора. При диагностике этого уровня сохраняйте версию схемы и контракт API рядом с полезными данными; изменение знаков препинания не исправит правильно проанализированное значение неправильной формы.
Уровень третий: смысл
Смысл зависит от фактов и правил, выходящих за рамки статической формы документа. `accountId` может иметь правильный шаблон строки, не называя учетной записи. Дата начала может соответствовать формату стиля ISO, но при этом находиться после даты окончания. Количество может быть положительным, но превышать текущий запас. Эти сбои требуют контекста приложения, сохраненного состояния или связей между полями.
Некоторые семантические ограничения можно аппроксимировать в схеме, но многие относятся к логике сервиса, где доступны авторитетные данные и состояние транзакции. Ответы на ошибки на этом уровне должны идентифицировать соответствующее поле или правило, не притворяясь, что текст JSON был искажен. ToolAcre не может воспроизвести эти решения, поскольку он не знает контракт и не отправляет входные данные приложению, которому принадлежит бизнес-правило.
Рабочий пример: одна полезная нагрузка через три проверки
Начните с `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre принимает его: все имена и значения соответствуют грамматике JSON. Затем схеме может потребоваться объект, непустая строка SKU, положительное целое число и один из документированных кодов склада. Предположим, что эта полезная нагрузка тоже соответствует этим ограничениям. Ни одна проверка не подтвердила, что SKU A-19 существует или что на севере находятся три единицы.
Служба инвентаризации выполняет третью проверку текущих записей и может отклонить запрос как недоступный. Изменение отступов не может изменить этот результат. Если бы `quantity` было записано как `03`, сначала произошел бы сбой синтаксиса; если бы это было `"3"`, синтаксический анализ прошел бы, но проверка типа схемы завершилась бы неудачей; с числовым `3` остается только правило живого поголовья. Таким образом, одно и то же поле может выйти из строя на трех разных уровнях по трем различным причинам.
Где место каждого чека
Запускайте проверку синтаксиса как можно раньше во время редактирования, поскольку последующие проверки не могут надежно работать с текстом, который не анализируется. Применяйте объявленную форму на каждой границе недоверенного приложения, а не предполагайте, что клиент уже сделал это. Оценивайте бизнес-инварианты в компоненте, владеющем требуемым состоянием, особенно когда ответ может меняться между запросами.
Проверки на стороне клиента улучшают обратную связь, но не заменяют принудительное исполнение на стороне сервера. И наоборот, ответ сервера, говорящий «неверный JSON», должен быть зарезервирован для сбоя синтаксического анализа, а не использоваться для каждого отклоненного запроса. Четкое разделение дает полезную диагностику: строка и столбец для синтаксиса, пути экземпляров для структурных ограничений и коды или сообщения для конкретной предметной области для семантических конфликтов. ToolAcre предоставляет только первую категорию.
Что это не распространяется
Этот форматтер не создает и не оценивает JSON схему, не выбирает черновик схемы, не разрешает ссылки на схему, не вставляет значения по умолчанию и не преобразует строки в числа. Он также не знает документа OpenAPI API или пользовательских соглашений проверки. Предоставление схемы вместе с входными данными не изменит результат ToolAcre, поскольку в этом инструменте нет этапа обработки схемы.
Проверка синтаксиса также не обнаруживает здесь повторяющиеся имена объектов; `JSON.parse` сохраняет последнее вхождение перед форматированием. Он также не гарантирует числовую точность, канонические байты, безопасный рендеринг или авторизацию. Каждая из этих проблем требует своего собственного контракта и реализации. Не сжимайте их в один зеленый значок «действительно», поскольку это скроет, какие доказательства были собраны, а какие вопросы никогда не задавались.
Вывод: слово «действительно» требует уточнения
Квалифицируйте каждое утверждение проверки. «Действительный JSON» означает, что текст соответствует грамматике. «Действительно для этой схемы» означает, что проанализированное значение удовлетворяет именованному структурному контракту. «Принято службой» означает, что текущие правила приложения разрешают операцию. Во многих рабочих процессах передача одного слоя необходима для перехода к следующему, но это никогда не свидетельствует о том, что все последующие уровни прошли.
Используйте ToolAcre для форматирования и проверки строгого синтаксиса, включая отклонение литералов, отличных от JSON, таких как `NaN` и `Infinity`. Затем используйте схему и приложение, которые фактически управляют полезной нагрузкой. Если запрос по-прежнему терпит неудачу, прочитайте ошибку на ее собственном уровне вместо того, чтобы повторно форматировать правильный JSON. В этом инструменте нет проверок схемы, и такая явная граница более полезна, чем слишком широкое обещание достоверности.