JSON Tools Guide: Convert Documents and Data to JSON and Back

This guide explains how the JSON tools read and write files, the document format that PDF to JSON and Word to JSON produce, and which tool to use for each job.

Why JSON

JSON is the data format that programs, web services and AI models read most easily: objects with named fields, lists, numbers, text, true, false and null, nothing else. Documents and spreadsheets are not stored that way. The tools in this family bridge the gap in both directions: they turn PDFs, Word files, spreadsheets, CSV, YAML and XML into JSON, and they turn JSON back into files that people read, such as PDF, Word, Excel, CSV and HTML.

Every tool runs on our servers over a secure connection and deletes the uploaded file within 60 minutes. Text input can be pasted directly instead of uploaded.

Which Tool for Which Job

Markdown has its own pair: Markdown to JSON exports a document tree and JSON to Markdown turns JSON into a Markdown outline or table.

The Document Format

PDF to JSON and Word to JSON write the same shape, so one piece of code handles both. The top level always has these fields:

{
  "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": "a@b.com"}],
  "extraction": {"engine": "pdf_to_markdown/layout", "mode": "structure", "ocr": false, "warnings": []}
}

The fields mean the following:

• source: what the file was, with the metadata it carried (title, author, subject, keywords, creation and modification dates, page count). Word files add the word, table and image counts.
• pages: one entry per PDF page with its size in points, its rotation, a word count and its text. Word files have no pages, because Word lays pages out only when it prints. The page text comes from the same layout analysis that produces the blocks (text_source is "layout"), which reads right-to-left and shaped scripts in logical order; when the analysis finds nothing on a page, the raw text layer is used instead (text_source is "text-layer"). Text that is turned, such as a diagonal DRAFT watermark or a vertical axis label, is listed separately under rotated_text with its angle in degrees, in the order its own language reads. A label the layout analysis could not place in the reading order, such as a number printed inside a chart, is listed under unplaced_text rather than dropped or spliced into a sentence it is not part of.
• blocks: the document in reading order. Types are heading (with level 1 to 6), paragraph (with an optional style name from Word and, when it has hyperlinks, a links list of text and href), list (ordered or not, items with a nesting level), table (header plus typed rows), code, blockquote, rule, image and aside. Every block from a PDF carries its page number. Block text is plain text: no Markdown markers. An aside block is text outside the reading flow because it is turned: it is read along its own baseline, so it is neither lost nor scattered letter by letter into the lines it crosses. A Word cell that holds a nested table is an object with text and tables, so nothing inside it is lost, and merged cells are recorded under merged (row, col, rows, cols) with null continuation cells, so every row has the same number of cells. Word content that lives outside the body flow -- headers, footers, footnotes, endnotes and comments, the last with author and date -- is present whenever the document has it, and images carry their file name, content type, size in points and alt text.
• tables: for PDFs, every detected table with the page it was found on and, for a table that continues, the page it ends on. Cells that look like numbers are numbers. A grid the detector finds on a chart or a card layout (mostly empty, or one value repeated across a row) is not reported as a table; its text is still in the blocks.
• form_fields: present only when the PDF has a form. Each field has its name, type (text, choice, button or signature) and current value.
• extraction: which converter ran, the mode you chose, whether OCR was needed, and any warnings, such as a table that could not be detected.

Version 1 of this format only ever gains fields; existing fields keep their names and meaning.

Tabular Data and Nesting

CSV and Excel are flat, JSON is not. When JSON goes to CSV or Excel, nested objects are flattened into dotted column names and arrays into indexed ones, so an order record with a customer object and an items array becomes columns like customer.name, items[0].sku and items[1].sku. When CSV or Excel comes back to JSON, headers written that way are rebuilt into nested objects and arrays. A header with an ordinary dot in it, such as a version number or an abbreviation, is left alone.

Values are typed on the way in: numbers become numbers, true and false become booleans, an empty cell becomes null, and anything else stays a string. Dates coming out of Excel are written as ISO 8601 strings, because JSON has no date type. Switch the value types option to text when identifiers with leading zeros must stay exactly as written.

Excel to JSON reads the sheet the way a person does. The header row is the first row that is mostly text and spans the table; a merged title or an export id above it is kept, and that sheet becomes an object with title, notes and records instead of a bare list. A formula whose result the file never cached (workbooks written by libraries and exporters carry no cache) is calculated: arithmetic, percentages, text joins, comparisons and the common functions (SUM, AVERAGE, MIN, MAX, COUNT, IF, IFERROR, AND, OR, ROUND, ABS, SQRT, MOD, CONCAT, LEN and more), with Excel's own error values such as #DIV/0! and #N/A where Excel would show them. A formula outside that set is recalculated by the spreadsheet engine on the server when it is available, and otherwise shown as its text with a warning. Hidden sheets are included and named in the result's warnings.

CSV to JSON picks the delimiter that makes the rows uniform (comma, semicolon, tab or pipe), so a European file with decimal commas and semicolons parses correctly. A row with more cells than the header keeps its extra cells as "column N". Text that has no consistent delimiter is not a table: each line becomes one record with a single text field, and the result says so.

Validation and Repair

Every JSON tool validates its input the same way. An invalid file is refused with the line and column of the first mistake, and a short excerpt of that line. The JSON Formatter can also repair the mistakes people paste most often: comments, trailing commas, single-quoted strings, unquoted keys, capitalised True, False and None, NaN and Infinity, and code fences around the text. When a repair was applied the result tells you, so nothing silently changes behind your back.

Privacy

Uploaded files and pasted text are processed on our servers and deleted within 60 minutes; see the privacy guide for the details. Nothing is stored beyond that time and nothing is used for any other purpose.