How to Validate a JSON File with jq Before Importing to a Store

Файл обмена сохранился, но импорт его не принимает. До повторного запуска полезно проверить сам файл: есть ли в нём JSON, ровно один ли это документ и тот ли тип данных ожидает получатель. Успешный разбор синтаксиса отвечает только на первый из этих вопросов.

Руководство рассчитано на Linux, оболочку Bash и уже установленный jq версии 1.7. Проверки выполнены 27 сентября 2026 года в изолированной среде Linux с jq-1.7 на небольших учебных файлах. Команды читают локальную копию; настройки, службы и данные магазина не меняются. Нужны обычные права чтения файла, административные права не требуются.

Работайте с разрешённой копией без паролей и данных покупателей. В примерах ./payload.json — путь к вашему локальному файлу в текущем каталоге. Замените его на нужный путь; имя с пробелами заключите в кавычки. Не перенаправляйте вывод обратно в исходный файл: для диагностики перезапись не нужна.

Сначала подтвердите версию утилиты:

jq --version

Если программы нет, остановитесь и согласуйте её установку отдельно. Ошибка доступа к файлу также не означает повреждение JSON. Она означает, что проверка содержимого пока не состоялась. Полный рабочий пакет не стоит отправлять в случайный онлайн-валидатор.

jq empty ./payload.json

Фильтр empty не печатает разобранные значения. Поэтому корректный файл обычно даст пустой вывод. Сразу после команды прочитайте код завершения:

echo $?

Это код предыдущей команды в Bash. Не запускайте между проверкой и его чтением другие команды. Ноль означает успешное выполнение этого фильтра. Ненулевой код нужно разбирать вместе с сообщением об ошибке: причиной бывают синтаксис, недоступный файл или неверный запуск.

В учебном файле с пропущенным значением после двоеточия утилита сообщила об ошибке разбора и указала строку со столбцом. Это место обнаружения, а не обязательно место первоначальной ошибки: например, незакрытая кавычка могла появиться раньше. Не исправляйте рабочую выгрузку наугад; передайте обезличенный фрагмент тому, кто формирует пакет.

На стенде пустой файл тоже прошёл jq empty с кодом ноль. Последовательность из двух объектов {} и {} также прошла: утилита умеет читать поток отдельных JSON-значений. Но ваш метод импорта может требовать ровно один объект. Для него оба таких файла непригодны.

Если контракт требует один JSON-объект верхнего уровня, используйте отдельную проверку:

jq -e -s 'length == 1 and (.[0] | type == "object")' ./payload.json

Параметр -s собирает прочитанные значения в массив. Условие проверяет, что значение одно и что это объект. Параметр -e позволяет использовать результат условия как код завершения. В наших примерах один объект дал true и код ноль; пустой файл, два объекта, массив и null дали false и код один. Повреждённый JSON завершился ошибкой разбора.

Здесь важно назначение проверки. Если API по договору принимает массив заказов, отклонение массива этим фильтром будет ожидаемым результатом неправильно выбранного условия. Нельзя превращать требование одного конкретного метода в правило для всех JSON-файлов.

У режима -s есть цена: он собирает весь вход в памяти. Эти команды проверены на маленьких файлах. Не запускайте такую проверку на многогигабайтной выгрузке загруженного сервера; для больших потоков нужен отдельно спроектированный разбор с ограничением ресурсов. Малый пример не подтверждает приемлемую нагрузку большого пакета.

Объект может успешно пройти обе команды и всё равно содержать неверные поля, неизвестный идентификатор или отрицательное количество. Синтаксический разбор и проверка верхнего уровня не подтверждают схему, права на изменение заказа и допустимость бизнес-операции.

Отдельно учитывайте повторяющиеся имена свойств. Стандарт JSON рекомендует уникальные имена; программы могут обрабатывать повторы по-разному. Обычный успешный разбор не следует выдавать за проверку их отсутствия. Если контракт запрещает повторы, нужен механизм, который замечает их до потери сведений при преобразовании в объект.

Для обращения к разработчику сохраните версию jq, точную команду, код завершения и обезличенное сообщение. Добавьте правило получателя: один объект, массив или согласованный поток. Тогда формулировка «файл не импортируется» превращается в проверяемый результат: синтаксис читается, но число документов или верхний тип не совпадает с контрактом. После устранения этой границы можно переходить к проверке полей и тестовому импорту.

The exchange file was saved, but the import rejected it. Before retrying, it is useful to check the file itself: does it contain JSON, is it exactly one document, and does the receiver expect that data type? Successful syntax parsing answers only the first of these questions.

This guide is intended for Linux, the Bash shell, and an already installed jq version 1.7. Checks were performed on September 27, 2026, in an isolated Linux environment with jq-1.7 on small test files. Commands read a local copy; store settings, services, and data remain unchanged. Standard file read permissions are required; administrative privileges are not needed.

Work with an authorized copy that contains no passwords or customer data. In the examples, ./payload.json represents the path to your local file in the current directory. Replace it with the required path; enclose names with spaces in quotes. Do not redirect output back to the source file: overwriting is unnecessary for diagnostics.

First, confirm the utility version:

jq --version

If the program is missing, stop and arrange its installation separately. An error accessing the file does not indicate JSON corruption. It means the content check has not yet occurred. Do not send a full working package to a random online validator.

jq empty ./payload.json

The empty filter does not print parsed values. Therefore, a valid file typically produces empty output. Immediately after the command, read the exit code:

echo $?

This is the code from the previous Bash command. Do not run other commands between the check and reading it. A zero value means the filter executed successfully. A non-zero code must be analyzed together with the error message: the cause can be syntax errors, an inaccessible file, or incorrect execution.

In the sample file with a missing value after the colon, the utility reported a parsing error and indicated the line and column. This is the location of detection, not necessarily the location of the original error: for example, an unclosed quote might have appeared earlier. Do not guess-fix a working export; pass an anonymized fragment to the person generating the package.

On the test stand, an empty file also passed jq empty with a zero code. A sequence of two objects, {} and {}, also passed: the utility can read a stream of individual JSON values. However, your import method may require exactly one object. For that case, both types of files are unsuitable.

If the contract requires a single top-level JSON object, use a separate check:

jq -e -s 'length == 1 and (.[0] | type == "object")' ./payload.json

The -s parameter collects the read values into an array. The condition checks that there is a single value and that it is an object. The -e parameter allows using the result of the condition as an exit code. In our examples, one object yielded true and exit code zero; an empty file, two objects, an array, and null yielded false and exit code one. A corrupted JSON file ended with a parse error.

The purpose of the check is important here. If the API contract accepts an array of orders, rejecting an array with this filter is the expected result of an incorrectly chosen condition. Do not turn a requirement for one specific method into a rule for all JSON files.

The -s mode has a cost: it loads the entire input into memory. These commands have been tested on small files. Do not run such a check on a multi-gigabyte export from a loaded server; for large streams, you need a separately designed parser with resource limits. A small example does not confirm that a large package can handle the load.

An object may successfully pass both checks and still contain invalid fields, an unknown identifier, or a negative quantity. Syntax parsing and top-level validation do not confirm the schema, order modification permissions, or the validity of the business operation.

Pay separate attention to duplicate property names. The JSON standard recommends unique names; programs may handle duplicates differently. Do not treat a standard successful parse as confirmation of their absence. If the contract forbids duplicates, a mechanism is needed to detect them before information is lost during conversion to an object.

To contact the developer, preserve the jq version, the exact command, the exit code, and an anonymized message. Add a recipient rule: one object, array, or consistent stream. This turns the statement "file does not import" into a verifiable result: syntax is readable, but the document count or top-level type does not match the contract. Once this boundary is resolved, proceed to field validation and test import.