Understanding output

Understanding the outputs

Layout categories and HTML tags

Upstage Document Parse identifies various layout categories in the input document and converts them to HTML tags.

The table below describes all layout categories and corresponding HTML tags. If there is no suitable HTML tag for the layout category, it uses a <p> tag with a data-category attribute to explain the layout category detected by the model. list is the one exception — in enhanced mode on document-parse-260930 and document-parse-nightly (including pages that auto mode processes as enhanced), it returns a real <ul> or <ol> element with <li> items instead, and the list kind is available in the element's sub_category field (ul or ol).

Some elements also carry a sub_category field — a finer, open-ended classification within a category. For example, a figure may be a signature, stamp, qr_code, or bar_code; a chart may be a line, bar, or pie; a heading1 carries its heading level (h2 to h6, omitted for a level-1 heading); and a code block reports its programming language (such as python). The value set is open and grows over time, so treat sub_category as an arbitrary string rather than a fixed set of values. The field is omitted when the model does not provide a sub-classification. Heading levels, list kinds, and the code category come from the enhanced mode parser on document-parse-260930 and document-parse-nightly.

A detailed example of layout categories can be seen in the example below.

Equation recognition

For the equation category output, the model provides recognized text in LaTex format within the <p data-category="equation"> tag to ensure proper display using popular equation rendering engines like MathJax. The output of a sample equation image can be seen below.

{
  "category": "equation",
  "content": {
      "html": "<p id='3' data-category='equation'>$$a_{n}=\\sum_{k=1}^{n}{\\frac{2k+1}{\\,1^{2}+2^{2}+3^{2}+\\cdots+k^{2}}}$$</p>",
      "markdown": "$$a_{n}=\\sum_{k=1}^{n}{\\frac{2k+1}{\\,1^{2}+2^{2}+3^{2}+\\cdots+k^{2}}}$$,
      "text": "n 2k+1 \nan  \nk=1 12+22+32 + · · +k2"
  },
}

In the response, the content.html and content.markdown fields contain the recognized equation in LaTex format, while the content.text field contains the OCR result text. Because the OCR model does not support equation recognition at the moment, the content.text field may not contain the correct equation text. For equation category, the OCR result in the content.text field is provided for backward compatibility.

Users may have difficulty rendering the content.html field value properly in their HTML file. This is because the API response in JSON format escapes the \\ character. To resolve this issue, they can use JavaScript to unescape the HTML. The example code below demonstrates how to render the equation properly in an HTML file by importing the MathJax library and unescaping the API response. The sanitizer step also allows every tag and attribute Document Parse can emit across all layout categories (see the table above), not just the <p> tag this equation example uses — so other elements in your document aren't silently stripped.

<body>
    <div id="equation"></div> <!-- placeholder for equation -->
    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>
    <script type="text/javascript">
        // Sanitize the API response before assigning it to innerHTML
        // to avoid XSS from any unexpected HTML in the parser output.
        const rawHtml = "<p id='5' data-category='equation'>$$f(x)=a_{0}+\\sum_{n=1}^{\\infty}\\left(a_{n}\\cos{\\frac{n\\pi x}{L}}+b_{n}\\sin{\\frac{n\\pi x}{L}}\\right)$$</p>"
        const safeHtml = DOMPurify.sanitize(rawHtml, {
            ALLOWED_TAGS: [
                // paragraph-style categories, including caption, and list when it is not rendered as ul/ol
                'p',
                // list markup (enhanced mode on document-parse-260930 and document-parse-nightly)
                'ul', 'ol', 'li',
                // headings (enhanced mode on document-parse-260930 and document-parse-nightly carries the depth in sub_category,
                // so a heading element can be any of h1..h6) and structural regions
                'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'footer', 'br',
                // tables, including nested and chart tables
                'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'colgroup', 'col', 'caption',
                // figures, charts, and images
                'figure', 'figcaption', 'img',
                // code blocks
                'pre', 'code',
                // inline text styling and checkboxes (enhanced mode on document-parse-260930 and document-parse-nightly)
                'b', 'strong', 'i', 'em', 's', 'del', 'u', 'mark', 'sup', 'sub', 'input',
            ],
            ALLOWED_ATTR: ['id', 'data-category', 'data-coord', 'alt', 'class', 'type', 'checked'],
            // `style` is left out on purpose. Document Parse only uses it to carry a
            // `font-size` hint, and allowing the attribute wholesale lets CSS that came
            // from the document reposition or overlay your own UI. If you want the hint,
            // add 'style' back and validate the value in an `uponSanitizeAttribute` hook
            // so that nothing but `font-size` survives.
        })
        document.getElementById('equation').innerHTML = safeHtml
    </script>
</body>

Please note that users can also obtain the base64 encoded image of the equation from the original document by specifying ["equation"] in the base64_encoding field of the request body.

Four-decimal format coordinates

Since document-parse-240910, users can employ relative coordinates when drawing bounding boxes or cropping elements from input documents. The absolute position can be calculated by multiplying the x and y values in the coordinates field of each item by the width and height of the requested image.

"coordinates": [
    {
      "x": 0.0276,
      "y": 0.0178
    },
    {
      "x": 0.1755,
      "y": 0.0178
    },
    {
      "x": 0.1755,
      "y": 0.0641
    },
    {
      "x": 0.0276,
      "y": 0.0641
    }
]