---
title: "SchemaGenerationSettings"
canonical_url: "https://www.nutrient.io/api/python/settings/vision/schema-generation-settings/"
md_url: "https://www.nutrient.io/api/python/settings/vision/schema-generation-settings.md"
last_updated: "2026-07-15T14:46:57.766Z"
description: "Settings for SchemaGeneration. Values fall back through three levels: document → SDK → built-in default."
---

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`

```python

from nutrient_sdk import SchemaGenerationSettings

```

## Construction

`SchemaGenerationSettings` is accessed through a [`Document`](/api/python/document/) instance for per-document overrides, or via [`SdkSettings`](/api/python/settings/document/sdk-settings/) for SDK-wide defaults.

```python

# 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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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`](/api/python/enums/schema-compatibility/)

**Default:** `SchemaCompatibility.Portable`

---

### include_constraints

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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`

---

---

## Related pages

- [Vision](/api/python/settings/vision.md)
- [Per-document override](/api/python/settings/vision/document-classification-settings.md)
- [Per-document override](/api/python/settings/vision/vision-settings.md)