# 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

```json
{
  "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.
