JSON schema (v11.0)

Top-level blocks of the export produced by bibr chew / POST /papers/extract. The Pydantic model bibr.export.models.PaperExport is the single source of truth for output structure. Schema validation does not establish factual accuracy.

Download the generated JSON Schema. This uses the same schema builder as the checked-in export artifact, including its required-root-field contract.

Top-level blocks

Block	Type	Description
`paper_id`	`str \| None`	Paper identifier: user-supplied --paper-id, else the DOI, else the source file name.
`schema_version`	`Literal['11.0']`	Export schema version. Its presence at the root is how readers distinguish v11 from all earlier versions.
`source`	`SourceExport`	Identity of the input artifact: file name, content hash, and format.
`metadata`	`MetadataExport`	Scalar paper-level metadata: title, abstract, keywords, DOI, paper-type and OECD classification, the paper's own journal/venue identity, and research-integrity statement text.
`author`	`list[AuthorExport]`	Extracted authors, with name, affiliation, email, corresponding-author flag, ORCID, and contribution roles.
`text`	`list[TextExport]`	Full body text as an ordered array of sentence-level spans, each linked to its paragraph, section, and page.
`section`	`list[SectionExport]`	Document section headers with hierarchy (level, parent) and IMRaD classification.
`url`	`list[UrlExport]`	Hyperlinks found in the body text, with their link text and source sentence.
`bib`	`list[BibExport]`	Parsed bibliography entries, verbatim from the printed reference list — never backfilled from external enrichment.
`xref`	`list[XrefExport]`	In-text citation/cross-reference markers linking a sentence to a bibliography entry, table, figure, footnote, equation, or section.
`figure`	`list[FigureExport]`	Extracted figures with caption, page number, and (optionally) base64-encoded image data.
`table`	`list[TableExport]`	Extracted tables with HTML markup, structured cell contents, caption, and page number.
`eq`	`list[EqExport]`	Parsed statistical/mathematical expressions split into left-hand side, degrees of freedom, comparator, and right-hand side.
`bib_match`	`list[BibMatchExport]`	Flattened enrichment matches (e.g. Crossref) for bibliography entries, one row per external-service hit.
`metadata_match`	`list[MetadataMatchExport]`	Enrichment matches for the paper's own bibliographic identity (self-DOI lookup), shaped like bib_match minus bib_id.
`funding`	`list[FundingExport]`	Structured funder names and award IDs parsed from the funding statement.
`affiliation`	`list[AffiliationExport]`	Structured author affiliations parsed from the byline: verbatim text plus best-effort institution/department/city/country and linked author IDs.
`qualification_provenance`	`dict \| None`	Deployment-qualification provenance: identity SHAs, per-task protocol hashes, native-validity + fallback outcome, and request counts. Always present; null (never omitted) when no LLM ran or usage tracking is disabled.
`extraction`	`ExtractionExport \| None`	Extraction provenance: how this output was produced — engines, per-run settings, timings, LLM usage, enrichment, identity receipts, diagnostics and warnings; omitted when exported outside the pipeline.
`validation`	`ValidationExport \| None`	Output validation gate result: counts of errors/warnings and the structured issue list; absent when the gate was skipped.

Reading an export

The root schema_version identifies the output schema; extraction.bibr_version identifies the producing package. Paper fields live in metadata, input identity in source, and telemetry in extraction. Table rows connect through IDs: text.section_id points to section.section_id, and xref links a source text_id to an object identified by xref_type and xref_id. Do not treat IDs as array positions.

bib starts with parsed references. bib_match and metadata_match hold external enrichment separately. Explicit consolidation (fill or replace) can update reference fields and records consolidated_fields. See enrichment and consolidation.

Optional blocks may be absent rather than null. extraction.regions requires include_regions=True / --regions; per-sentence underscore fields require include_region_meta=True / --region-meta. The validation gate is enabled by default and can be disabled independently of the typed export builder. Inspect extraction.warnings and validation when reviewing results. The root schema_version key distinguishes v11 from legacy exports. For compatibility and structured reference names, see the export overview.

Nested record fields

These tables describe the models referenced above. Required means required by the model constructor; a nullable field may still be required. Defaults do not guarantee that a field is emitted: the exporter omits selected optional and debug fields.

SourceExport

Field	Type	Required	Default
`file_name`	`str`	Yes	—
`file_hash`	`str`	Yes	—
`input_format`	`str`	Yes	—

MetadataExport

Field	Type	Required	Default
`title`	`str \| None`	Yes	—
`abstract`	`str \| None`	No	`None`
`keywords`	`list[str]`	Yes	—
`doi`	`str \| None`	Yes	—
`paper_type`	`str \| None`	No	`None`
`paper_type_confidence`	`float \| None`	No	`None`
`oecd_l1`	`str \| None`	No	`None`
`oecd_l2`	`str \| None`	No	`None`
`oecd_confidence`	`float \| None`	No	`None`
`journal`	`str \| None`	No	`None`
`volume`	`str \| None`	No	`None`
`issue`	`str \| None`	No	`None`
`first_page`	`str \| None`	No	`None`
`last_page`	`str \| None`	No	`None`
`issn`	`str \| None`	No	`None`
`publisher`	`str \| None`	No	`None`
`published`	`str \| None`	No	`None`
`license`	`str \| None`	No	`None`
`funding_statement`	`str \| None`	No	`None`
`coi_statement`	`str \| None`	No	`None`
`ethics_statement`	`str \| None`	No	`None`
`data_availability`	`str \| None`	No	`None`

AuthorExport

Field	Type	Required	Default
`author_id`	`int`	Yes	—
`given`	`str`	Yes	—
`family`	`str`	Yes	—
`suffix`	`str \| None`	No	`None`
`affiliation`	`str \| None`	No	`None`
`email`	`str \| None`	No	`None`
`corresponding`	`bool`	Yes	—
`orcid`	`str \| None`	No	`None`
`role`	`list[str]`	No	`[]`

TextExport

Field	Type	Required	Default
`text`	`str`	Yes	—
`text_id`	`int`	Yes	—
`paragraph_id`	`int`	Yes	—
`section_id`	`int \| None`	Yes	—
`page_number`	`int \| None`	Yes	—
`formatted`	`str \| None`	No	`None`
`_font_size`	`float \| None`	No	`None`
`_font_bold`	`bool \| None`	No	`None`
`_is_italic`	`bool \| None`	No	`None`
`_bbox_2d`	`list[float] \| None`	No	`None`
`_region_type`	`str \| None`	No	`None`
`_page_w`	`float \| None`	No	`None`
`_page_h`	`float \| None`	No	`None`

SectionExport

Field	Type	Required	Default
`section_id`	`int`	Yes	—
`header`	`str`	Yes	—
`level`	`int`	Yes	—
`parent_section_id`	`int \| None`	Yes	—
`section_type`	`str \| None`	Yes	—
`classification_score`	`float`	Yes	—
`classification_source`	`str \| None`	No	`None`

UrlExport

Field	Type	Required	Default
`href`	`str`	Yes	—
`link_text`	`str \| None`	Yes	—
`text_id`	`int`	Yes	—

BibExport

Field	Type	Required	Default
`bib_id`	`int`	Yes	—
`text_id`	`int \| None`	No	`None`
`bib_type`	`str \| None`	No	`None`
`doi`	`str \| None`	No	`None`
`title`	`str \| None`	No	`None`
`authors`	`str \| None`	No	`None`
`author`	`list[PersonNameExport] \| None`	No	`None`
`editors`	`str \| None`	No	`None`
`editor`	`list[PersonNameExport] \| None`	No	`None`
`publisher`	`str \| None`	No	`None`
`year`	`int \| None`	No	`None`
`year_suffix`	`str \| None`	No	`None`
`date`	`str \| None`	No	`None`
`container`	`str \| None`	No	`None`
`volume`	`str \| None`	No	`None`
`issue`	`str \| None`	No	`None`
`first_page`	`str \| None`	No	`None`
`last_page`	`str \| None`	No	`None`
`edition`	`str \| None`	No	`None`
`version`	`str \| None`	No	`None`
`url`	`str \| None`	No	`None`
`is_in_press`	`bool`	No	`False`
`arxiv`	`str \| None`	No	`None`
`pmid`	`str \| None`	No	`None`
`series`	`str \| None`	No	`None`
`access_date`	`str \| None`	No	`None`
`note`	`str \| None`	No	`None`
`consolidated_fields`	`str \| None`	No	`None`

PersonNameExport

Field	Type	Required	Default
`family`	`str \| None`	No	`None`
`given`	`str \| None`	No	`None`
`suffix`	`str \| None`	No	`None`
`literal`	`str \| None`	No	`None`

XrefExport

Field	Type	Required	Default
`target_id`	`int \| None`	Yes	—
`xref_type`	`Literal['bib', 'table', 'figure', 'foot', 'supplementary', 'equation', 'section']`	Yes	—
`contents`	`str \| None`	Yes	—
`text_id`	`int`	Yes	—
`tier`	`Literal['numeric', 'paren-numeric', 'flattened-superscript', 'author-year', 'llm'] \| None`	No	`None`

FigureExport

Field	Type	Required	Default
`figure_id`	`int`	Yes	—
`section_id`	`int \| None`	No	`None`
`image`	`str \| None`	No	`None`
`caption`	`str \| None`	No	`None`
`page_number`	`int \| None`	Yes	—
`parts`	`list[FigurePartExport]`	No	`[]`

FigurePartExport

Field	Type	Required	Default
`part_index`	`int`	Yes	—
`image`	`str \| None`	No	`None`
`page_number`	`int \| None`	No	`None`
`bbox`	`list[float] \| None`	No	`None`
`provenance`	`list[ProvenanceExport]`	No	`[]`

ProvenanceExport

Field	Type	Required	Default
`page`	`int`	Yes	—
`bbox`	`list[float] \| None`	No	`None`

TableExport

Field	Type	Required	Default
`table_id`	`int`	Yes	—
`section_id`	`int \| None`	No	`None`
`html`	`str \| None`	No	`None`
`contents`	`list[list[str]]`	Yes	—
`caption`	`str \| None`	No	`None`
`page_number`	`int \| None`	Yes	—
`parts`	`list[TablePartExport]`	No	`[]`

TablePartExport

Field	Type	Required	Default
`part_index`	`int`	Yes	—
`html`	`str \| None`	No	`None`
`contents`	`list[list[str]]`	Yes	—
`page_number`	`int \| None`	No	`None`
`bbox`	`list[float] \| None`	No	`None`
`provenance`	`list[ProvenanceExport]`	No	`[]`

EqExport

Field	Type	Required	Default
`eq_id`	`int`	Yes	—
`text_id`	`int`	Yes	—
`grp_id`	`int`	Yes	—
`verbatim`	`str \| None`	No	`None`
`lhs`	`str`	Yes	—
`df`	`str`	Yes	—
`comp`	`str`	Yes	—
`rhs`	`str`	Yes	—

BibMatchExport

Field	Type	Required	Default
`bib_id`	`int`	Yes	—
`service`	`str`	Yes	—
`service_id`	`str \| None`	No	`None`
`score`	`float \| None`	No	`None`
`bib_type`	`str \| None`	No	`None`
`doi`	`str \| None`	No	`None`
`title`	`str \| None`	No	`None`
`author`	`list[PersonNameExport] \| None`	No	`None`
`editor`	`list[PersonNameExport] \| None`	No	`None`
`publisher`	`str \| None`	No	`None`
`year`	`int \| None`	No	`None`
`date`	`str \| None`	No	`None`
`container`	`str \| None`	No	`None`
`volume`	`str \| None`	No	`None`
`issue`	`str \| None`	No	`None`
`first_page`	`str \| None`	No	`None`
`last_page`	`str \| None`	No	`None`
`edition`	`str \| None`	No	`None`
`version`	`str \| None`	No	`None`
`url`	`str \| None`	No	`None`

MetadataMatchExport

Field	Type	Required	Default
`service`	`str`	Yes	—
`service_id`	`str \| None`	No	`None`
`score`	`float \| None`	No	`None`
`bib_type`	`str \| None`	No	`None`
`doi`	`str \| None`	No	`None`
`title`	`str \| None`	No	`None`
`author`	`list[PersonNameExport] \| None`	No	`None`
`editor`	`list[PersonNameExport] \| None`	No	`None`
`publisher`	`str \| None`	No	`None`
`year`	`int \| None`	No	`None`
`date`	`str \| None`	No	`None`
`container`	`str \| None`	No	`None`
`volume`	`str \| None`	No	`None`
`issue`	`str \| None`	No	`None`
`first_page`	`str \| None`	No	`None`
`last_page`	`str \| None`	No	`None`
`edition`	`str \| None`	No	`None`
`version`	`str \| None`	No	`None`
`url`	`str \| None`	No	`None`

FundingExport

Field	Type	Required	Default
`funding_id`	`int`	Yes	—
`funder`	`str`	Yes	—
`award_ids`	`list[str]`	No	`[]`

AffiliationExport

Field	Type	Required	Default
`affiliation_id`	`int`	Yes	—
`text`	`str`	Yes	—
`institution`	`str \| None`	No	`None`
`department`	`str \| None`	No	`None`
`city`	`str \| None`	No	`None`
`country`	`str \| None`	No	`None`
`author_ids`	`list[int]`	No	`[]`

ExtractionExport

Field	Type	Required	Default
`bibr_version`	`str`	Yes	—
`build_sha`	`str \| None`	No	`None`
`completed_at`	`str`	Yes	—
`ocr`	`OcrEngineExport \| None`	No	`None`
`llm`	`LlmEngineExport \| None`	No	`None`
`settings`	`ExtractionSettingsExport`	Yes	—
`timings`	`TimingsExport \| None`	No	`None`
`usage`	`UsageExport \| None`	No	`None`
`enrichment`	`EnrichmentExport \| None`	No	`None`
`identity`	`IdentityExport \| None`	No	`None`
`diagnostics`	`DiagnosticsExport \| None`	No	`None`
`warnings`	`list[str]`	No	(computed)
`regions`	`list[RegionExport] \| None`	No	`None`
`trace`	`list[LlmTraceExport] \| None`	No	`None`

OcrEngineExport

Field	Type	Required	Default
`backend`	`str \| None`	No	`None`
`model`	`str \| None`	No	`None`
`profile`	`Literal['paddle', 'glm'] \| None`	No	`None`

LlmEngineExport

Field	Type	Required	Default
`provider`	`str \| None`	No	`None`
`model`	`str \| None`	No	`None`
`backend`	`str \| None`	No	`None`

ExtractionSettingsExport

Field	Type	Required	Default
`ref_seg`	`str`	Yes	—
`ref_parse`	`str`	Yes	—
`crossref_enrich`	`bool`	Yes	—
`consolidate`	`str`	Yes	—

TimingsExport

Field	Type	Required	Default
`stages`	`dict[str, float] \| None`	No	`None`
`total_seconds`	`float \| None`	No	`None`

UsageExport

Field	Type	Required	Default
`totals`	`UsageTotalsExport`	Yes	—
`breakdown`	`list[UsageRowExport]`	No	(computed)

UsageTotalsExport

Field	Type	Required	Default
`calls`	`int`	Yes	—
`input_tokens`	`int`	Yes	—
`cached_input_tokens`	`int`	Yes	—
`output_tokens`	`int`	Yes	—
`total_tokens`	`int`	Yes	—

UsageRowExport

Field	Type	Required	Default
`label`	`str`	Yes	—
`provider`	`str \| None`	No	`None`
`model`	`str \| None`	No	`None`
`calls`	`int`	Yes	—
`input_tokens`	`int`	Yes	—
`cached_input_tokens`	`int`	Yes	—
`output_tokens`	`int`	Yes	—
`total_tokens`	`int`	Yes	—

EnrichmentExport

Field	Type	Required	Default
`complete`	`bool`	Yes	—
`refs_enriched`	`int`	Yes	—
`refs_total`	`int`	Yes	—

IdentityExport

Field	Type	Required	Default
`expected`	`ExpectedIdentityExport \| None`	No	`None`
`receipt`	`IdentityReceiptExport \| None`	No	`None`

ExpectedIdentityExport

Field	Type	Required	Default
`queue_record_id`	`str`	Yes	—
`expected_doi`	`str \| None`	No	`None`
`expected_doi_sha256`	`str \| None`	No	`None`
`expected_title`	`str \| None`	No	`None`
`target_block_hint`	`dict[str, object] \| None`	No	`None`
`source_sha256`	`str \| None`	No	`None`
`doi_required`	`bool`	No	`False`

IdentityReceiptExport

Field	Type	Required	Default
`selected`	`DoiCandidateExport \| None`	No	`None`
`candidates`	`list[DoiCandidateExport]`	No	(computed)
`issue_codes`	`list[str]`	No	(computed)

DoiCandidateExport

Field	Type	Required	Default
`raw`	`str`	Yes	—
`normalized`	`str`	Yes	—
`source_kind`	`str`	Yes	—
`page`	`int \| None`	Yes	—
`section_id`	`int \| None`	Yes	—
`section_type`	`str \| None`	Yes	—
`region_index`	`int \| None`	Yes	—
`region_type`	`str \| None`	Yes	—
`text_id`	`int \| None`	Yes	—
`marker_kind`	`str`	Yes	—
`repeated_header_footer_count`	`int`	Yes	—
`semantic_context`	`str`	Yes	—
`selection_tier`	`int`	Yes	—
`rejection_reason`	`str \| None`	No	`None`

DiagnosticsExport

Field	Type	Required	Default
`text_quality`	`float \| None`	No	`None`
`references_complete`	`bool`	No	`True`
`ref_seg_fallback_used`	`bool`	No	`False`
`citation_linking`	`CitationLinkingExport \| None`	No	`None`
`caption_assignment`	`CaptionAssignmentReceiptExport \| None`	No	`None`
`reference_yield`	`ReferenceYieldExport \| None`	No	`None`

CitationLinkingExport

Field	Type	Required	Default
`style_scores`	`dict[str, float]`	Yes	—
`candidates`	`list[CitationCandidateExport]`	Yes	—
`resolved_candidate_fraction`	`float \| None`	Yes	—
`unique_linked_bib_fraction`	`float \| None`	Yes	—

CitationCandidateExport

Field	Type	Required	Default
`text_id`	`int`	Yes	—
`start`	`int`	Yes	—
`end`	`int`	Yes	—
`raw`	`str`	Yes	—
`style`	`str`	Yes	—
`bib_ids`	`list[int]`	Yes	—
`evidence`	`list[str]`	Yes	—
`confidence`	`float`	Yes	—
`accepted`	`bool`	Yes	—
`rejection_reasons`	`list[str]`	Yes	—

CaptionAssignmentReceiptExport

Field	Type	Required	Default
`candidates`	`list[CaptionCandidateExport]`	Yes	—
`assignments`	`list[CaptionAssignmentExport]`	Yes	—

CaptionCandidateExport

Field	Type	Required	Default
`caption_id`	`str`	Yes	—
`text`	`str`	Yes	—
`object_type`	`str`	Yes	—
`page_number`	`int \| None`	Yes	—
`bbox`	`list[float] \| None`	Yes	—
`source_index`	`int`	Yes	—

CaptionAssignmentExport

Field	Type	Required	Default
`caption_id`	`str`	Yes	—
`object_id`	`str \| None`	Yes	—
`score`	`float`	Yes	—
`reasons`	`list[str]`	Yes	—
`ambiguous`	`bool`	No	`False`

ReferenceYieldExport

Field	Type	Required	Default
`credible_source_starts`	`int \| None`	Yes	—
`attempts`	`list[ReferenceSegmentationAttemptExport]`	Yes	—
`selected_spans`	`list[list[int]]`	Yes	—
`source_character_coverage`	`float \| None`	Yes	—
`parsed_count`	`int`	Yes	—
`valid_count`	`int`	Yes	—
`duplicate_rate`	`float`	Yes	—
`reason_flags`	`list[str]`	Yes	—

ReferenceSegmentationAttemptExport

Field	Type	Required	Default
`strategy`	`str`	Yes	—
`spans`	`list[list[int]]`	Yes	—
`credible_starts`	`int \| None`	Yes	—
`selected`	`bool`	Yes	—
`reason_flags`	`list[str]`	Yes	—

RegionExport

Field	Type	Required	Default
`page`	`int`	Yes	—
`index`	`int`	Yes	—
`label`	`str \| None`	Yes	—
`bbox`	`list[float] \| None`	Yes	—
`font_size`	`float \| None`	No	`None`
`font_weight`	`float \| None`	No	`None`
`font_bold`	`bool \| None`	No	`None`
`section_id`	`int \| None`	No	`None`
`content`	`str \| None`	No	`None`
`raw_ocr_content`	`str \| None`	No	`None`
`bbox_height`	`float \| None`	No	`None`
`bbox_width`	`float \| None`	No	`None`
`char_density`	`float \| None`	No	`None`
`estimated_line_height`	`float \| None`	No	`None`

LlmTraceExport

Field	Type	Required	Default
`label`	`str`	Yes	—
`provider`	`str \| None`	No	`None`
`model`	`str \| None`	No	`None`
`messages`	`list[dict]`	No	(computed)
`raw_completion`	`str \| None`	No	`None`
`parsed_ok`	`bool`	Yes	—
`finish_reason`	`str \| None`	No	`None`
`params`	`dict`	No	(computed)
`attempt`	`int`	No	`1`
`error`	`str \| None`	No	`None`

ValidationExport

Field	Type	Required	Default
`errors`	`int`	Yes	—
`warnings`	`int`	Yes	—
`blocking`	`int`	No	`0`
`promotable`	`bool`	No	`True`
`issues`	`list[ValidationIssueExport]`	Yes	—

ValidationIssueExport

Field	Type	Required	Default
`code`	`str`	Yes	—
`severity`	`str`	Yes	—
`message`	`str`	Yes	—
`origin_stage`	`str`	No	`'export'`
`evidence_ids`	`list[str]`	No	(computed)
`count`	`int`	Yes	—
`blocking`	`bool`	No	`False`