Jacob Collins Jacob is the JPedal Product Manager and specialises in PDF creation and manipulation. He also develops Salesforce backend systems and contributes to marketing and support. Outside of work, he’s a 1900‑rated chess player, guitarist, and French learner.

How to extract structured content from a PDF as JSON Lines in Java

6 min read

JPedal Java PDF library logo

TL;DR JSON Lines (JSONL) is JSON with one complete object per line. We recently added it to JPedal as an output mode for structured content, writing one line for each block-level element in a tagged PDF: a heading, a paragraph, a list, a table, etc. Set the output mode on an instance of ExtractStructuredTextProperties to OutputModes.JSONL and pass it to ExtractStructuredText.writeAllStructuredTextOutlinesToDir(). As with every structured format, the PDF has to be tagged. An untagged PDF has no structured content to export.

Contents:

  1. What is a tagged PDF?
  2. What is JSON Lines (JSONL)?
  3. JSON vs JSONL
  4. Requirements
  5. How to extract structured content as JSONL
  6. What the output looks like
  7. Frequently asked questions

What is a tagged PDF?

A tagged PDF contains information about its own structure: a hierarchy of tags that label the headings, paragraphs, lists, tables and figures on each page. It works a lot like HTML, where text sits inside elements such as <h1> or <p> that describe what they mean.

That structure is what JPedal extracts. If a PDF was not tagged when it was created, there is nothing to export. Not sure about yours? See how to find out if a PDF file has structured content, or learn more about tagged PDF files.

What is JSON Lines (JSONL)?

JSON Lines, or JSONL, is a plain text format where every line is a complete, valid JSON value, usually an object. Lines are separated by a newline character, and files normally use the .jsonl extension.

Because each line stands on its own, a program can read the file one line at a time without loading or parsing the whole thing first. That makes it a common format for logs, data exports, and the datasets used to train and feed AI models.

JSON vs JSONL

A JSON file is a single document. To read any part of it, a parser has to read all of it, and a mistake anywhere in the file makes the whole thing invalid. That is okay for a small API response or a settings file, but not for a large document you want to process piece by piece.

JSONL splits that single document into independent records. You can stream it, append to it, count it with wc -l, or filter it with grep and jq.

When JPedal extracts structured content as JSON, the whole document ends up in one tree. With JSONL, each heading, paragraph, list, table and figure gets its own line instead, written in the same way ({"Name": {"attributes": ..., "children": [...]}}) that the JSON output uses. The text and attributes are the same in both. What JSONL drops is the nesting of grouping elements such as Sect, so if you need to know which section a paragraph sits in, use JSON.

That split is what makes JSONL useful for AI work. A RAG (retrieval-augmented generation) pipeline needs to break a document into chunks before it can embed and index them. A tagged PDF already knows where its headings, paragraphs and tables begin and end, so you can build chunks along the author’s own structure instead of cutting at an arbitrary character count. A line is not a chunk on its own, though. Many paragraphs are only a few words long, so the usual approach is to start a new chunk at each heading and add lines to it until you reach your size limit. Most lines also carry the page number they came from, which you can keep for citations. If you want something closer to readable text for an LLM, extracting the content as Markdown is the better fit.

Requirements

  • A JPedal jar, version 2026.11 or later, either the trial or a licensed build, on your class or module path
  • Java 17 or later
  • A tagged PDF file

How to extract structured content as JSONL

JPedal supports extracting structured content as JSONL through the ExtractStructuredText class. Set the output mode on an ExtractStructuredTextProperties object, then pass it in as the last parameter:

final ExtractStructuredTextProperties properties = new ExtractStructuredTextProperties();
properties.setFileOutputMode(OutputModes.JSONL);

ExtractStructuredText.writeAllStructuredTextOutlinesToDir("inputFile.pdf", password, "outputFolder", null, properties);

The input can be a single PDF or a folder of them, and password is the PDF’s password, or null if it does not have one. The fourth parameter is an optional ErrorTracker, which you can leave as null.

To write the document’s figures out as images alongside the JSONL, use writeAllStructuredTextOutlinesAndFiguresToDir() instead. It takes the same parameters, followed by a folder for the figures, the image format to write them in, and a scaling factor (1.0f is the original size):

ExtractStructuredText.writeAllStructuredTextOutlinesAndFiguresToDir("inputFile.pdf", password, "outputFolder", null, properties, "figuresFolder", imageFormat, 1.0f);

You don’t need to write any Java to try it. The same class runs from the command line, which also lets you call it from other languages:

java --module-path . --add-modules com.idrsolutions.jpedal org/jpedal/examples/text/ExtractStructuredText "inputFileOrFolder" "outputFolder" "jsonl"

The output is written to the output folder with the same name as the PDF, so inputFile.pdf becomes inputFile.jsonl. If the PDF has no structured content, that file will have no lines in it, so check for an empty file before you pass it on to the next step of your pipeline.

What the output looks like

Each line is an object with a single key, the name of the structure element, holding its attributes (if it has any) and its children. Text sits in {"text": "..."} objects. These are the first lines extracted from the PDF Association’s Well-Tagged PDF (WTPDF) specification:

{"Figure": {"attributes": {"BBox": "[210.916, 710.552, 384.359, 790.085]", "Placement": "Block", "alt": "PDF Association Logo", "pg": "1"}}}
{"H1": {"attributes": {"SpaceAfter": "19.0", "SpaceBefore": "73.0", "TextAlign": "Center", "pg": "1"}, "children": [{"text": "Well-Tagged PDF (WTPDF) Using Tagged PDF for Accessibility and Reuse in PDF 2.0"}]}}
{"P": {"attributes": {"SpaceAfter": "8.0", "SpaceBefore": "48.0", "TextAlign": "Center", "pg": "1"}, "children": [{"text": "PDF Association"}]}}
{"P": {"attributes": {"pg": "1"}, "children": [{"text": "PDF Reuse TWG & PDF/UA TWG"}]}}
{"P": {"attributes": {"pg": "1"}, "children": [{"text": "Version 1.0.0"}]}}

The pg attribute is the page the element came from, and a figure’s alt text is in alt. The whole document comes out as 765 lines: 535 paragraphs, 184 headings, 23 lists, 11 code blocks, 10 tables, a table of contents and a figure.

Three things are worth knowing:

  • Grouping elements are unwrapped. Most tagged PDFs put everything inside a Document element, often with Part, Sect, Art or Div elements below it. If those were written as lines, the whole document would come out as one line. JPedal writes their children as lines instead. If a grouping element has attributes, they are written on their own line just before its contents, so no data is lost.
  • Lists and tables stay whole. A list or table is a block-level element, so it is written as a single line with its items or rows nested inside: LI elements holding an Lbl (the bullet or number) and an LBody, or TR rows holding TH and TD cells. You will not get a line per list item or table cell.
  • Line lengths vary a lot. The shortest lines in the WTPDF output are a few words. The longest, a table, is over 8,800 characters. Check the size of each line before you pass it to anything with a token limit.

Each line is a complete JSON object, so you can read the file one line at a time with nothing more than the standard library and hand each line to the JSON parser of your choice:

try (BufferedReader reader = Files.newBufferedReader(Path.of("outputFolder/inputFile.jsonl"))) {
    String line;
    while ((line = reader.readLine()) != null) {
        // each line is one heading, paragraph, list, table or figure
    }
}

JSONL is one of several output modes. The same code can write structured content as ePUB, HTML, JSON, Markdown, XML or YAML by changing the OutputModes value.

Frequently asked questions

What is the difference between JSON and JSONL?

A JSON file is one value, usually an object or array, that has to be parsed as a whole. A JSONL (JSON Lines) file is a sequence of separate JSON values, one per line, that can be read and processed one at a time.

Can all PDF files be converted to JSONL?

No. Only PDFs that contain structured or tagged content can be converted. Untagged PDFs may still allow plain text extraction, but there is no structure to split into lines. If you can’t get any text out at all, see why can I not extract text from this PDF file?

Why use JSONL for RAG?

A RAG pipeline has to split documents into chunks before embedding them. JSONL output from a tagged PDF gives you the document one heading, paragraph, list or table at a time, so you can build chunks that follow the structure the author gave the document instead of cutting text mid-sentence.

Does the output include page numbers?

Yes. Most elements have a pg attribute holding the page they came from. On lists and tables it sits on the items and cells inside them rather than on the line’s top-level element.

Which version of JPedal supports JSONL?

JSONL output was added in JPedal 2026.11, released on 11th November 2026. Earlier versions support the other structured content formats but not JSONL.

Should I use JSON or JSONL?

Use JSON if you want the full document tree in one piece, for example to return from an API. Use JSONL if you want to stream the content or process it one element at a time, such as chunking it for a RAG pipeline.

We have been working with PDFs for over 25 years and have other resources to help you learn more about the PDF format.