Schemas and provenance
Supported schema profile
Nugget accepts a constrained JSON Schema 2020-12 profile, not arbitrary schemas.
Schemas must be objects. Boolean schemas, $ref, and $defs are unsupported.
Property names must be nonempty and cannot contain dots. Maximum schema depth
is 20 and maximum leaf-field count is 500, so every chunk's answer fits the model's
output budget. Provider output-schema limits can impose additional restrictions.
Supported keywords: $schema, title, description, type, properties,
required, enum, additionalProperties, items, minItems, maxItems,
uniqueItems, minProperties, maxProperties, multipleOf, oneOf, anyOf,
allOf, minimum, maximum, minLength, maxLength, pattern, format,
default, and const. x- extension keys are accepted. A keyword's acceptance
does not imply all providers enforce it identically; format is not an automatic
guarantee of format validation.
Extraction result
{
"data": {"invoice_number": "123", "items": [{"price": 12.5}]},
"provenance": {
"/invoice_number": {"confidence": 0.98, "evidence": [], "error": null},
"/items/0/price": {"confidence": 0.91, "evidence": [], "error": null}
},
"bbox_convention": {"unit": "normalized", "origin": "top-left", "y_axis": "down"},
"provenance_granularity": "scalar",
"provenance_truncated": false
}
This abbreviated example illustrates shape, not a guarantee of evidence for every
field. data contains plain values, so it can be passed to downstream business
logic without recursive wrapper removal. provenance uses RFC 6901 JSON
Pointers into data: zero-based array indexes, ~0 for ~, and ~1 for /.
Missing/unavailable values may be null, with field errors such as
missing_in_chunk. Explicit null and missing values are not always distinguishable
from the data alone. Inspect provenance. Extraction produces schema-shaped data,
but does not promise every result satisfies all constraints of the submitted
schema. Validate locally before business use. Infer and Review have their own
output-validation contracts.
Array provenance depends on options.expand_arrays: false for container-level,
"items" for item-level, or "leaves" for nested leaf-level detail.
max_array_items defaults to 1000 (maximum 5000); max_total_fields defaults to
10000 (maximum 50000). Check provenance_truncated; absent provenance does not
mean a value was verified or that it is erroneous.
Evidence and coordinates
Confidence is a model signal, not a calibrated probability. Evidence quotes and matching scores are different signals. A matching quote does not prove a claim follows from it. Review/Summarize citation validation checks references; it is not a proof of factual entailment for every generated claim.
Pages are 1-based. Bounding boxes are normalized, with a top-left origin and downward y-axis; they are not pixel coordinates. CSV/XLSX evidence may have no bounding box. Page dimensions, when available, identify their own units.
OCR doc_start/doc_end are zero-based, end-exclusive offsets into returned
text; page offsets index that page's text. When selecting pages, returned text
joins selected pages in document order with two newlines and offsets are remapped.
Use Unicode character indexing, not UTF-8 byte positions.
Normalization
Normalization can alter a value while retaining raw_value in provenance.
Normalization options use the documented field-path syntax; do not assume those
legacy option keys are interchangeable with output JSON Pointers. Unknown
options and overlong instructions are rejected rather than silently truncated.