Инструменты разработчика · JSON форматировщик и валидатор
Почему у JSON нет комментариев: дизайнерское решение и обходные пути
· Фон
JSON стандарты проверка
Комментарии были удалены из JSON намеренно. В этом посте объясняются причины, почему каждая попытка добавить их обратно создает новый формат и какие у вас есть варианты, когда файл конфигурации действительно нуждается в примечании.
Комментарий, который сломал сборку
Комментарий, который сломал сборку — полезное примечание, добавленное в конфигурацию JSON и парсер, который остановился на первой косой черте. Возможно, автор скопировал шаблон из JavaScript или редактора, поддерживающего JSONC, тогда как инструмент развертывания использует строгий JSON. Подсветка синтаксиса может сделать заметку законной, даже если потребитель отклоняет первый маркер комментария.
Комментарии отклоняются, поскольку косая черта не является токеном JSON, где сканер ожидает значение или член. ToolAcre не удаляет автоматически синтаксис JSONC или JSON5. Обычное свойство в форме комментария представляет собой обычные данные и может нарушать схему приложения, даже если его принимает строгий синтаксис JSON. Неподтвержденные исторические утверждения о конструкции JSON опускаются или исправляются, а не представляются как установленный факт без первичных доказательств или прослеживаемого источника стандартов, доступного для проверки.
Причина, по которой Крокфорд удалил комментарии
Причина удаления комментариев Крокфордом — в более позднем объяснении говорится, что комментарии использовались для передачи директив синтаксического анализа, что подрывало совместимость между реализациями. Соответствующим следствием проектирования является то, что стандарт JSON не имеет токена комментария. Утверждения о частных мотивах, точной хронологии или универсальной реакции отрасли требуют исторических источников, не предоставленных этим хранилищем.
Соответственно, необоснованные исторические утверждения здесь опущены или исправлены. Наблюдаемого стандарта и поведения синтаксического анализатора достаточно: строгий JSON обменивается данными через шесть типов значений и два контейнера без канала аннотаций. Это ограничение не позволяет одному получателю придавать рабочее значение тексту, который игнорирует другой получатель, но оно также делает JSON менее удобным для настройки вручную.
Что сообщает валидатор по комментарию
Что сообщает валидатор по комментарию — `//` и `/* */` отсутствуют в грамматике, поэтому ошибка приходится на первую косую черту со строкой и столбцом. Сканер не возражает против слов в заметке. Никакое допустимое значение JSON, имя элемента или разделитель не могут начинаться с `/` в этой позиции.
Для `{"port":8080, // только локально "secure":false}`, запятая действительна, а следующим допустимым токеном должно быть имя свойства в кавычках или закрывающая скобка. Слэш нарушает это ожидание. Удаление только примечания оставляет действительный разделитель и следующий член; удаление соседних знаков препинания может привести к второй ошибке. Повторно проверяйте точный строгий вывод после каждого редактирования.
Форматы, в которые добавлены комментарии обратно
Форматы, которые добавляли комментарии обратно: JSONC позволяет комментировать знакомый синтаксис JSON, а JSON5 добавляет такие удобства, как ключи идентификатора без кавычек и конечные запятые. Hjson делает упор на редактирование человеком с помощью дополнительного упрощенного синтаксиса. YAML имеет собственную грамматику, включая комментарии, а не просто JSON с добавленными аннотациями.
Принятие зависит от потребителя: настройки редактора и конфигурация TypeScript могут использовать анализаторы, устойчивые к комментариям, тогда как манифест пакета или тело API могут требовать строгого JSON. Kubernetes обычно использует YAML или JSON в зависимости от своего инструментария. Назовите фактический формат в документации и обработке файлов; удаление расширений или вызов нотации каждого объекта «JSON» скрывает границы совместимости.
Обходные пути внутри строгого JSON
Обходные пути внутри строгого JSON — обычный ключ `_comment` или `//` хранит объяснение как обычный строковый элемент. Он выдерживает строгий анализ, поскольку и ключ, и значение используют стандартные токены. Для нескольких заметок требуются уникальные ключи или массив, поскольку повторяющиеся имена элементов ненадежны и могут быть свернуты анализаторами.
Обходной путь меняет модель данных. Схема с `additionalProperties: false` может отклонить аннотацию, а приложение может сохранить или передать ее как реальную конфигурацию. Внешняя документация, соседний README или схема `description` часто обеспечивают более безопасный канал объяснения. Используйте элементы в форме комментариев только тогда, когда каждый потребитель явно разрешает и игнорирует их.
Рабочий пример: аннотированный файл настроек.
Рабочий пример: аннотированный файл настроек — начинается с источника JSONC, содержащего `// seconds before retry` выше `"timeout":30`. Если пункт назначения принимает только JSON, используйте анализатор, который понимает JSONC, для создания данных, а затем сериализуйте эти данные как строгие JSON. Развернутый артефакт становится `{"timeout":30}`, а поддерживаемый источник сохраняет свое объяснение.
Не удаляйте комментарии с помощью регулярного выражения. Последовательности косых черт могут законно появляться внутри строк, таких как URL-адреса, а шаблоны блочных комментариев могут охватывать строки таким образом, что некорректно обрабатывается текстовая замена. Сохраняйте исходный и сгенерированный артефакты отдельно, проверяйте строгий результат и организуйте регенерацию в сборке. Это сохраняет примечания автора, не делая вид, что принимающий синтаксический анализатор их поддерживает.
Что это не распространяется
Что здесь не рассматривается — как настроить отдельные парсеры для приема комментариев, которые зависят от инструмента и часто меняются. Разрешающая опция в одной библиотеке не изменяет грамматику JSON и не гарантирует, что другая служба примет тот же текст. Проверьте парсер, версию и место назначения, а не полагайтесь на дисплей редактора.
В этой статье также избегаются необоснованные утверждения о том, когда именно были удалены комментарии, кто первым применил каждый обходной путь или стало ли одно только дизайнерское решение причиной популярности JSON. Такие исторические утверждения нуждаются в независимых первоисточниках. Здесь они опущены или исправлены; Поддерживаемый вывод ограничен текущим строгим синтаксисом, поведением репозитория и эксплуатационными различиями между именованными форматами.
Вывод: JSON — это формат обмена данными, а не язык конфигурации.
Вывод: JSON — это формат обмена данными, а не язык конфигурации с множеством комментариев, и валидатор точно показывает, где примечание нарушает строгую грамматику. Когда людям нужны аннотации, выберите формат, который официально поддерживает инструмент-потребитель, или сохраните аннотированный источник, который генерирует отдельный строгий артефакт. Не думайте, что комментарии будут безобидно игнорироваться.
Если строгий JSON является обязательным, переместите объяснение в документацию или используйте метаданные, одобренные схемой, а затем проверьте окончательный документ. ToolAcre намеренно сообщает о первой косой черте вместо автоматического удаления материала, поскольку автоматическое преобразование может изменить строки или скрыть несоответствие формата. Исторический контекст должен оставаться в равной степени дисциплинированным: необоснованные утверждения опускаются или исправляются, а наблюдаемый синтаксис и поведение синтаксического анализатора позволяют сделать вывод.