SchemaGenerationSettings

Settings for SchemaGeneration. Values fall back through three levels: document → SDK → built-in default. Writes target the document only when set on a document’s settings, otherwise the SDK globally when set on SdkSettings.

Tags: Vision

from nutrient_sdk import SchemaGenerationSettings

Construction

# Per-document override
with Document.open("input.pdf") as doc:
    settings = doc.settings.schema_generation_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)
SdkSettings.schema_generation_settings.some_field = new_value

Settings are configured by writing to fields on the returned object. The settings property itself cannot be reassigned — doc.settings.schema_generation_settings = other_settings is rejected.

Properties

allow_discriminated_unions

@property
def allow_discriminated_unions(self) -> bool

@allow_discriminated_unions.setter
def allow_discriminated_unions(self, value: bool) -> None

Enable discriminated unions: variant object types expressed as anyOf with a shared constant discriminator field per variant. oneOf is never used — it is rejected by OpenAI strict mode and silently ignored by Gemini. When false (default), the schema contains no union types beyond null unions.

Type: bool

Default: false

allow_enums

@property
def allow_enums(self) -> bool

@allow_enums.setter
def allow_enums(self, value: bool) -> None

Enable enum constraints for fields with a small closed set of known values. Default is true.

Type: bool

Default: true

allow_nullable

@property
def allow_nullable(self) -> bool

@allow_nullable.setter
def allow_nullable(self, value: bool) -> None

Enable nullable fields in the generated schema. Nullability is expressed as a type union with null (for example, "type": ["string", "null"]) — the only form accepted across the major structured-output modes. When false, every field is non-nullable. Default is true.

Type: bool

Default: true

allow_patterns

@property
def allow_patterns(self) -> bool

@allow_patterns.setter
def allow_patterns(self, value: bool) -> None

Enable regex pattern constraints on string fields. Off by default: pattern support differs widely between structured-output modes (several reject common shorthand classes such as \d), so patterns are only generated when explicitly enabled.

Type: bool

Default: false

allow_string_formats

@property
def allow_string_formats(self) -> bool

@allow_string_formats.setter
def allow_string_formats(self, value: bool) -> None

Enable string format annotations (for example, date-time or uuid), restricted to the formats the target dialect documents as supported. Default is true.

Type: bool

Default: true

compatibility

@property
def compatibility(self) -> SchemaCompatibility

@compatibility.setter
def compatibility(self, value: SchemaCompatibility) -> None

Target dialect preset applied on top of the individual knobs. The effective rule is always the stricter of the knob and the dialect limit; features the selected dialect documents as rejected are never emitted. Default is Portable — the intersection accepted by all major structured-output modes.

Type: SchemaCompatibility

Default: SchemaCompatibility.Portable

include_constraints

@property
def include_constraints(self) -> bool

@include_constraints.setter
def include_constraints(self, value: bool) -> None

Also generate cross-field constraint rules encoding the logical relationships of the document type (for example, a subtotal equaling the sum of line item amounts), as standard JsonLogic expressions (jsonlogic.com). The result is always an envelope object with a schema property (the JSON Schema) and a constraints array; this knob only controls whether constraints are generated — when false (default), the array is empty. Rules referencing fields that don’t exist in the generated schema are dropped, so the constraints always validate against the schema they ship with.

Type: bool

Default: false

max_array_items

@property
def max_array_items(self) -> int

@max_array_items.setter
def max_array_items(self, value: int) -> None

When greater than zero, bounds the number of items of arrays in the generated schema. Emitted as a maxItems constraint when the target dialect supports it, and as description text otherwise (the portable and Anthropic dialects reject maxItems). Zero (default) leaves arrays unbounded.

Type: int

Default: 0

max_fields

@property
def max_fields(self) -> int

@max_fields.setter
def max_fields(self, value: int) -> None

Maximum total number of properties across the whole generated schema, counting nested objects and union variants. Schemas exceeding the bound are truncated, keeping the most relevant fields first. Values above 200 are clamped to 200. Default is 50.

Type: int

Default: 50

max_nesting_depth

@property
def max_nesting_depth(self) -> int

@max_nesting_depth.setter
def max_nesting_depth(self, value: int) -> None

Maximum object nesting depth of the generated schema. Structures deeper than the bound are flattened. The root object is depth one. Dialect presets may cap this further (OpenAI strict mode and the portable intersection allow at most five levels). Default is three.

Type: int

Default: 3

max_retries

@property
def max_retries(self) -> int

@max_retries.setter
def max_retries(self, value: int) -> None

How many times to retry the vision model when its output is invalid — unparseable JSON or a draft that fails meta-schema validation. Each retry feeds the specific validation errors back to the model. Zero disables retries; there is no upper bound (each retry is a full model call, so the cost is yours to choose). Default is one.

Type: int

Default: 1