Boxes and Granularity
How fine should the annotation go?
✅ NormativeSettled. The requirement holds as written.📄 Page ruleCan be applied from the page alone.Read §3.3 in the RFC ↗
A box is the region of the page that an element's printed content occupies. Boxes MUST be given at exactly the granularity that was requested, and at that granularity every element MUST have one box. A producer MUST NOT return several granularities in place of one.
Reading the examples. Each one pairs a source page with the output the rule expects. ✅ Sample: the rule applies. ❌ Counter-sample: it looks like it applies and does not, or a rendering got it wrong. A non-conforming output, in red, is shown only for contrast. … marks content left out of an excerpt.
The point, in a small example
Switch between three requests for the exact same page. Region boxes remain; finer boxes change with the requested level. The result must not mix line and word ranges. These pages are made up to isolate the rule.
The same service page at element granularity
This interior page has a level-2 section heading, one two-line paragraph and a footer. Element boxes were requested. The Markdown and sidecar below are separate deliverables; the footer is not part of the paragraph. Coordinates use the original 720×420 image, not its on-screen display size.
Source page
Expected output
<!-- el p=1 x=48 y=54 w=179 h=22 -->
## Service note
<!-- el p=1 x=48 y=131 w=159 h=62 -->
Check valve A.
Record 12 psi.
<!-- el p=1 x=48 y=369 w=74 h=17 -->
Rev B | 7Expected output · Sidecar JSON
{
"pages": [
{
"page": 1,
"width": 720,
"height": 420,
"items": [
{
"type": "Section-header",
"md": "## Service note",
"bBox": {
"x": 48,
"y": 54,
"w": 179,
"h": 22
}
},
{
"type": "Text",
"md": "Check valve A.\nRecord 12 psi.",
"bBox": {
"x": 48,
"y": 131,
"w": 159,
"h": 62
}
},
{
"type": "Page-footer",
"md": "Rev B | 7",
"bBox": {
"x": 48,
"y": 369,
"w": 74,
"h": 17
}
}
]
}
]
}The same service page at line granularity
This interior page has a level-2 section heading, one two-line paragraph and a footer. Line boxes were requested. The Markdown and sidecar below are separate deliverables; the footer is not part of the paragraph. Coordinates use the original 720×420 image, not its on-screen display size.
Source page
Expected output
<!-- el p=1 x=48 y=54 w=179 h=22 -->
## Service note
<!-- el p=1 x=48 y=131 w=159 h=62 -->
Check valve A.
Record 12 psi.
<!-- el p=1 x=48 y=369 w=74 h=17 -->
Rev B | 7Expected output · Sidecar JSON
{
"pages": [
{
"page": 1,
"width": 720,
"height": 420,
"items": [
{
"type": "Section-header",
"md": "## Service note",
"bBox": {
"x": 48,
"y": 54,
"w": 179,
"h": 22
},
"layoutAwareBbox": [
{
"x": 48,
"y": 54,
"w": 179,
"h": 22,
"startIndex": 3,
"endIndex": 15
}
]
},
{
"type": "Text",
"md": "Check valve A.\nRecord 12 psi.",
"bBox": {
"x": 48,
"y": 131,
"w": 159,
"h": 62
},
"layoutAwareBbox": [
{
"x": 48,
"y": 131,
"w": 159,
"h": 17,
"startIndex": 0,
"endIndex": 14
},
{
"x": 48,
"y": 171,
"w": 153,
"h": 22,
"startIndex": 15,
"endIndex": 29
}
]
},
{
"type": "Page-footer",
"md": "Rev B | 7",
"bBox": {
"x": 48,
"y": 369,
"w": 74,
"h": 17
},
"layoutAwareBbox": [
{
"x": 48,
"y": 369,
"w": 74,
"h": 17,
"startIndex": 0,
"endIndex": 9
}
]
}
]
}
]
}The same service page at word granularity
This interior page has a level-2 section heading, one two-line paragraph and a footer. Word boxes were requested. The Markdown and sidecar below are separate deliverables; the footer is not part of the paragraph. Coordinates use the original 720×420 image, not its on-screen display size.
Source page
Expected output
<!-- el p=1 x=48 y=54 w=179 h=22 -->
## Service note
<!-- el p=1 x=48 y=131 w=159 h=62 -->
Check valve A.
Record 12 psi.
<!-- el p=1 x=48 y=369 w=74 h=17 -->
Rev B | 7Expected output · Sidecar JSON
{
"pages": [
{
"page": 1,
"width": 720,
"height": 420,
"items": [
{
"type": "Section-header",
"md": "## Service note",
"bBox": {
"x": 48,
"y": 54,
"w": 179,
"h": 22
},
"layoutAwareBbox": [
{
"x": 48.0,
"y": 54,
"w": 108.0,
"h": 22,
"startIndex": 3,
"endIndex": 10
},
{
"x": 164.0,
"y": 55,
"w": 63.0,
"h": 21,
"startIndex": 11,
"endIndex": 15
}
]
},
{
"type": "Text",
"md": "Check valve A.\nRecord 12 psi.",
"bBox": {
"x": 48,
"y": 131,
"w": 159,
"h": 62
},
"layoutAwareBbox": [
{
"x": 48.0,
"y": 131,
"w": 67.0,
"h": 17,
"startIndex": 0,
"endIndex": 5
},
{
"x": 122.0,
"y": 131,
"w": 55.0,
"h": 17,
"startIndex": 6,
"endIndex": 11
},
{
"x": 183.0,
"y": 131,
"w": 24.0,
"h": 17,
"startIndex": 12,
"endIndex": 14
},
{
"x": 48.0,
"y": 171,
"w": 76.0,
"h": 17,
"startIndex": 15,
"endIndex": 21
},
{
"x": 131.0,
"y": 171,
"w": 26.0,
"h": 17,
"startIndex": 22,
"endIndex": 24
},
{
"x": 164.0,
"y": 171,
"w": 37.0,
"h": 22,
"startIndex": 25,
"endIndex": 29
}
]
},
{
"type": "Page-footer",
"md": "Rev B | 7",
"bBox": {
"x": 48,
"y": 369,
"w": 74,
"h": 17
},
"layoutAwareBbox": [
{
"x": 48.0,
"y": 369,
"w": 32.0,
"h": 13,
"startIndex": 0,
"endIndex": 3
},
{
"x": 85.0,
"y": 369,
"w": 12.0,
"h": 13,
"startIndex": 4,
"endIndex": 5
},
{
"x": 102.0,
"y": 369,
"w": 5.0,
"h": 17,
"startIndex": 6,
"endIndex": 7
},
{
"x": 112.0,
"y": 369,
"w": 10.0,
"h": 13,
"startIndex": 8,
"endIndex": 9
}
]
}
]
}
]
}What a box covers
A box MUST enclose all of its element's printed content and SHOULD enclose nothing else. What belongs to an element — whether a caption is inside a table's box, whether a list item's box includes its bullet, where a picture ends — is decided by the layout rules: Block Boundaries (§5.2), Block Annotation (§5.1) and Block Classes (§5.3). A box never covers content moved out of its position in the Markdown: a watermark's box is where the watermark is printed.
The four levels
| Level | A box is given for… | Suited to |
|---|---|---|
| none | each element (region level) | the default: region-level grounding |
| cell | each element, and each table cell | per-value verification and highlighting |
| line | each element, and each printed line | line-level citation, reading-order checks |
| word | each element, and each word | per-token grounding |
The levels are a ladder
The levels subsume one another, and the resolution rule is strict precedence:
word > line > cell > none
A request naming several levels MUST be served at the finest one named; naming coarser levels alongside it changes nothing.
Choosing a level
Finer is not better. Each step down multiplies the number of boxes, and every box can be wrong, mis-attributed or drift out of alignment with its text. A consumer SHOULD request the coarsest level that answers its question.
Where a rule turns on geometry — is this value printed once or three times? does this ruling line stop before that column? — the evidence lives at cell level or finer. A coarser output can neither settle nor dispute those questions.
Neighbouring rules, and how they differ
More
Rule id output-boxes-and-granularity · output output-model boxes layout