PDF source-map JSON: trace Markdown blocks back to available evidence
A source map is useful only when it separates observed evidence from missing data. pdfmd exports page attribution, Markdown offsets, provider method, and any returned coordinates or confidence without filling gaps with invented values.
Short answer: Use source-map JSON as a review index, not as proof that extraction is correct. Validate schema_version, locate a Markdown span by its offsets, reopen the reported page, and treat null coordinates or confidence as unavailable evidence.
What pdfmd.source-map.v1 records
| Level | Fields | Meaning |
|---|---|---|
| document | file name, page count, Markdown, export time | The converted artifact |
| page | dimensions, method, offsets, block IDs | Page-level attribution when available |
| block | type, page, Markdown, method, offsets | One extracted unit |
| optional evidence | bbox, confidence, provider source | Nullable because providers differ |
The top-level schema_version is the compatibility contract. Consumers should reject or migrate an unfamiliar version instead of assuming every future file has the same fields. RFC 8259 defines JSON objects as unordered name/value collections, so downstream code must address fields by name rather than rely on their display order.
How to verify one extracted claim
- Find the claim in document.markdown and confirm the block's markdown_start and markdown_end select the same text.
- Open the reported source page and compare the full sentence, heading, table row, or note.
- Check method before interpreting confidence; different providers expose different evidence.
- If bbox or confidence is null, record it as unavailable instead of converting null into zero.
- Keep the source PDF and source map under the same dataset or document version.
"id": "p4b7",
"page": 4,
"method": "cloudflare",
"markdown_start": 1288,
"markdown_end": 1412,
"bbox": null,
"confidence": nullWhat a source map does not prove
Provenance helps assess reliability, but it is not the same as correctness. W3C PROV describes provenance as information about entities, activities, and agents involved in producing data. A page number and method can explain where output came from; they cannot prove that a table header, formula, reading order, or OCR character was interpreted correctly.
- Do not calculate an accuracy percentage from confidence values alone.
- Do not assume every block has coordinates just because the schema has a bbox field.
- Do not use Markdown offsets after editing the Markdown without regenerating the map.
- Do not discard the original PDF when the extracted material will support a consequential claim.
Official sources and evidence boundary
These links support format and platform behavior. pdfmd processing and point costs are governed by this site's pricing and privacy pages.
Keep the review checklist
Download the Markdown checklist and reuse it next time. Export-format changes are recorded in the public changelog.
Frequently asked questions
Is source-map JSON the same as a JavaScript source map?
No. This is a pdfmd document-provenance format that connects Markdown, pages, blocks, methods, and available evidence.
Why are bbox and confidence sometimes null?
Not every conversion provider returns coordinates or numeric confidence. Null means the evidence was unavailable, not zero.
Can I edit the Markdown and keep the old offsets?
No. Text edits can shift character positions. Regenerate or deliberately version the map after changing Markdown.
Does a source map prove the conversion is accurate?
No. It makes review traceable. Correctness still requires comparison with the PDF, especially for tables, formulas, columns, and OCR.
Export the evidence you actually have
Choose Source-map JSON after converting a real PDF. Sign-in and page points unlock cloud conversion; the exported map is downloaded locally and is not saved to an account library.