Skip to main content

The CoreConfig Specification

The CoreConfig object is the central mechanism for defining global validation and serialization behaviors in pydantic-core. It allows developers to configure how models, dataclasses, and typed dicts behave without needing to specify constraints on every individual field.

Configuration Hierarchy​

In pydantic-core, configuration can be applied at multiple levels. Understanding the precedence of these levels is crucial for predictable validation:

  1. Field-level constraints: Constraints defined directly on a field (e.g., max_length in str_schema) have the highest priority.
  2. Schema-specific config: Configuration embedded within a ModelSchema, DataclassSchema, or TypedDictSchema via the config attribute.
  3. Global config: Configuration passed to the SchemaValidator or SchemaSerializer constructor.

Global Application​

When initializing a SchemaValidator, the config argument applies settings to the entire schema tree unless overridden locally.

from pydantic_core import CoreConfig, SchemaValidator, core_schema as cs

# Global config enforcing a maximum string length
v = SchemaValidator(
    cs.str_schema(), 
    config=CoreConfig(str_max_length=5)
)

assert v.isinstance_python('short') is True
assert v.isinstance_python('too long') is False

Local Schema Application​

Specific schemas like ModelSchema can carry their own CoreConfig, which overrides the global settings for that specific model and its children.

class MyModel:
    __slots__ = '__dict__', '__pydantic_fields_set__', '__pydantic_extra__', '__pydantic_private__'

schema = cs.model_schema(
    cls=MyModel,
    config=CoreConfig(str_max_length=5),
    schema=cs.model_fields_schema(
        fields={'f': cs.model_field(schema=cs.str_schema())}
    ),
)
v = SchemaValidator(schema)

Core Validation Controls​

The CoreConfig class in pydantic_core/core_schema.py defines several flags that fundamentally change how validation is performed.

Strictness and Coercion​

  • strict: When True, the validator will not attempt to coerce types (e.g., it won't convert a string "123" to an integer).
  • coerce_numbers_to_str: Specifically enables coercion of numeric types to strings, which is useful when handling data from sources that don't distinguish between the two (ignored in strict mode).

Extra Fields Behavior​

The extra_fields_behavior attribute (using the ExtraBehavior type alias) determines how unknown keys are handled in dict-like structures:

  • 'ignore': (Default) Extra fields are silently dropped.
  • 'forbid': Validation fails if extra fields are present.
  • 'allow': Extra fields are preserved (usually in a __pydantic_extra__ dictionary on models).

Instance Revalidation​

The revalidate_instances setting controls whether existing instances of models or dataclasses should be re-validated when passed to a validator:

  • 'never': (Default) Existing instances are trusted.
  • 'always': Every instance is re-validated against the schema.
  • 'subclass-instances': Only instances of subclasses are re-validated.

Type-Specific Constraints​

CoreConfig provides global defaults for specific types, which is particularly useful for maintaining consistency across a large schema.

String Handling​

  • str_max_length / str_min_length: Global bounds for all string fields.
  • str_strip_whitespace: Automatically trims leading/trailing whitespace.
  • str_to_lower / str_to_upper: Forces casing on all strings.

Numeric and URL Handling​

  • allow_inf_nan: Controls whether float('inf') and float('nan') are valid (defaults to True).
  • url_preserve_empty_path: Determines if empty paths in URLs (like http://example.com) are kept as / or removed.

Serialization Settings​

Beyond validation, CoreConfig dictates how SchemaSerializer transforms Python objects into JSON-compatible formats.

Temporal and Binary Data​

  • ser_json_temporal: Defines the format for datetime, date, time, and timedelta. Options include 'iso8601', 'seconds', and 'milliseconds'.
  • ser_json_bytes: Controls how bytes are encoded in JSON. Options are 'utf8', 'base64', and 'hex'.

Handling Special Floats​

  • ser_json_inf_nan: Since standard JSON does not support Infinity or NaN, this setting defines the fallback:
    • 'null': (Default) Serializes to null.
    • 'constants': Serializes to Infinity, -Infinity, or NaN (non-standard JSON).
    • 'strings': Serializes to "Infinity", "-Infinity", or "NaN".

Integration with Complex Schemas​

The ModelSchema, DataclassSchema, and TypedDictSchema classes all include a config field of type CoreConfig.

TypedDict Specifics​

In TypedDictSchema, some configuration options have direct equivalents in the schema itself. For example, TypedDictSchema has a total boolean, while CoreConfig has typed_dict_total. The schema-level attribute typically takes precedence or is populated from the config during schema generation.

Dataclass Behavior​

For dataclasses, CoreConfig interacts with DataclassArgsSchema to manage how arguments are parsed before the dataclass is instantiated.

# Example of dataclass schema using config for revalidation
schema = cs.dataclass_schema(
    MyDataclass,
    cs.dataclass_args_schema(
        'MyDataclass',
        [cs.dataclass_field(name='a', schema=cs.str_schema())],
        extra_behavior='forbid',
    ),
    ['a'],
    revalidate_instances='always',
)

In this example, revalidate_instances is set at the DataclassSchema level, ensuring that even if a MyDataclass instance is already created, it will be checked again when passed through this validator.