NuggetAPI referenceAPI consoleOpenAPI

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.