Руководство по инструментам JSON: преобразование документов и данных в JSON и обратно
В этом руководстве описано, как инструменты JSON читают и пишут файлы и какой инструмент выбрать для каждой задачи.
Почему JSON
JSON, это формат данных, который программы, веб-сервисы и модели ИИ читают легче всего: объекты с именованными полями, списки, числа, текст, true, false и null, и больше ничего. Документы и электронные таблицы не хранятся таким образом. Инструменты этого семейства связывают эти два мира в обоих направлениях: они превращают PDF, файлы Word, электронные таблицы, CSV, YAML и XML в JSON, а также превращают JSON обратно в файлы, которые читают люди, такие как PDF, Word, Excel, CSV и HTML.
Каждый инструмент работает на наших серверах через защищённое соединение и удаляет загруженный файл в течение 60 минут. Текст можно вставить напрямую вместо загрузки файла.
Какой инструмент для какой задачи
| У Вас есть | Вы хотите получить | Используйте |
|---|---|---|
| Текст, таблицы и метаданные в виде данных | PDF в JSON | |
| Документ Word | Заголовки, абзацы, списки и таблицы в виде данных | Word в JSON |
| Книгу Excel | Записи, строки или столбцы | Excel в JSON |
| Файл CSV или TSV | Массив JSON с типизированными значениями | CSV в JSON |
| Файл YAML | Те же данные в виде JSON | YAML в JSON |
| Файл XML | Объекты, атрибуты и массивы | XML в JSON |
| JSON | PDF для чтения или печати | JSON в PDF |
| JSON | Книгу Excel | JSON в Excel |
| JSON | Файл CSV | JSON в CSV |
| JSON | Редактируемый документ Word | JSON в Word |
| JSON | Веб-страницу | JSON в HTML |
| JSON | YAML для конфигурационного файла | JSON в YAML |
| JSON | XML для другой системы | JSON в XML |
| JSON, который повреждён или некорректен | Чистый, корректный JSON | Форматирование JSON |
| Два файла JSON | Список того, что изменилось | Сравнить JSON |
У Markdown есть своя пара: Markdown в JSON экспортирует дерево документа, а JSON в Markdown превращает JSON в структуру или таблицу Markdown.
Формат документа
PDF в JSON и Word в JSON записывают одну и ту же форму, поэтому один и тот же код обрабатывает оба случая. На верхнем уровне всегда присутствуют такие поля:
{
"format": "acepdfmd-document",
"version": 1,
"source": {"type": "pdf", "filename": "report.pdf", "title": "Q3 Report", "pages": 12},
"pages": [{"number": 1, "width": 612, "height": 792, "words": 380, "text": "..."}],
"blocks": [
{"type": "heading", "level": 1, "text": "Q3 Report"},
{"type": "paragraph", "text": "Revenue grew..."},
{"type": "list", "ordered": false, "items": [{"level": 0, "text": "Europe"}]},
{"type": "table", "header": ["Region", "Q3"], "rows": [["Europe", 1200.5]]}
],
"tables": [{"index": 1, "page": 3, "rows": [["Region", "Q3"], ["Europe", 1200.5]]}],
"form_fields": [{"name": "email", "type": "text", "value": "[email protected]"}],
"extraction": {"engine": "pdf_to_markdown/layout", "mode": "structure", "ocr": false, "warnings": []}
}
Поля означают следующее:
- source: что представлял собой файл, с метаданными, которые он содержал (заголовок, автор, тема, ключевые слова, даты создания и изменения, количество страниц). Файлы Word дополнительно указывают количество слов, таблиц и изображений.
- pages: одна запись на каждую страницу PDF с её размером в пунктах, поворотом, количеством слов и текстом. У файлов Word нет страниц, потому что Word размещает страницы только при печати.
- blocks: документ в порядке чтения. Типы: heading (заголовок с уровнем от 1 до 6), paragraph (абзац с необязательным именем стиля из Word), list (список, упорядоченный или нет, с элементами и уровнем вложенности), table (таблица с заголовком и типизированными строками), code, blockquote, rule и image.
- tables: для PDF, каждая обнаруженная таблица со страницей, на которой она найдена, и, если таблица продолжается, страницей, на которой она заканчивается. Ячейки, похожие на числа, представлены числами.
- form_fields: присутствует только когда в PDF есть форма. У каждого поля есть имя, тип (text, choice, button или signature) и текущее значение.
- extraction: какой конвертер выполнял преобразование, выбранный режим, требовалось ли OCR, и любые предупреждения, например о таблице, которую не удалось обнаружить.
Версия 1 этого формата только получает новые поля; существующие поля сохраняют свои имена и значение.
Табличные данные и вложенность
CSV и Excel плоские, JSON, нет. Когда JSON превращается в CSV или Excel, вложенные объекты разворачиваются в имена столбцов с точками, а массивы, в пронумерованные, поэтому запись заказа с объектом клиента и массивом позиций становится столбцами вида customer.name, items[0].sku и items[1].sku. Когда CSV или Excel возвращается в JSON, заголовки, записанные таким образом, восстанавливаются во вложенные объекты и массивы. Заголовок с обычной точкой, например номер версии или сокращение, оставляется без изменений.
Значения типизируются на входе: числа становятся числами, true и false становятся логическими значениями, пустая ячейка становится null, а всё остальное остаётся строкой. Даты, приходящие из Excel, записываются как строки ISO 8601, поскольку в JSON нет типа даты. Переключите параметр типов значений на текст, когда идентификаторы с ведущими нулями должны остаться записанными в точности.
Проверка и исправление
Каждый инструмент JSON проверяет входные данные одинаковым образом. Некорректный файл отклоняется с указанием строки и столбца первой ошибки и коротким фрагментом этой строки. Форматирование JSON может также исправить ошибки, которые люди чаще всего вставляют: комментарии, висячие запятые, строки в одинарных кавычках, ключи без кавычек, написанные с большой буквы True, False и None, NaN и Infinity, и ограждения кода вокруг текста. Когда исправление применено, результат сообщает об этом, поэтому ничего не меняется незаметно для Вас.
Конфиденциальность
Загруженные файлы и вставленный текст обрабатываются на наших серверах и удаляются в течение 60 минут; подробности смотрите в руководстве по конфиденциальности. Ничего не хранится дольше этого времени и не используется для каких-либо иных целей.