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
| You have | You want | Use |
|---|---|---|
| A PDF | Text, tables and metadata as data | PDF to JSON |
| A Word document | Headings, paragraphs, lists and tables as data | Word to JSON |
| An Excel workbook | Records, rows or columns | Excel to JSON |
| A CSV or TSV file | A JSON array with typed values | CSV to JSON |
| A YAML file | The same data as JSON | YAML to JSON |
| An XML file | Objects, attributes and arrays | XML to JSON |
| JSON | A PDF to read or print | JSON to PDF |
| JSON | An Excel workbook | JSON to Excel |
| JSON | A CSV file | JSON to CSV |
| JSON | An editable Word document | JSON to Word |
| JSON | A web page | JSON to HTML |
| JSON | YAML for a configuration file | JSON to YAML |
| JSON | XML for another system | JSON to XML |
| JSON that is messy or invalid | Clean, valid JSON | JSON Formatter |
| Two JSON files | A list of what changed | Compare JSON |
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": "[email protected]"}],
"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.
- blocks: the document in reading order. Types are heading (with level 1 to 6), paragraph (with an optional style name from Word), list (ordered or not, items with a nesting level), table (header plus typed rows), code, blockquote, rule and image.
- 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.
- 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.
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.