JSON Schema API Reference¶

def resolve_refs(schema: dict[str, Any]) -> dict[str, Any]:
    """Resolve all local ``$ref`` pointers and inline their targets.

    Supports any JSON Pointer fragment (RFC 6901), including
    ``#/$defs/``, ``#/definitions/``, ``#/components/schemas/``, etc.
    After resolution, ``$defs`` and ``definitions`` maps are removed.

    Args:
        schema: A JSON Schema dict.

    Returns:
        A new dict with all ``$ref`` inlined and definition maps removed.
    """
    schema = copy.deepcopy(schema)
    result = _inline_refs(schema, schema)
    # Strip consumed definition maps.
    for key in _DEFS_KEYS:
        result.pop(key, None)
    return result

def merge_allof(schema: dict[str, Any]) -> dict[str, Any]:
    """Deep-merge all ``allOf`` sub-schemas into single schemas.

    Args:
        schema: A JSON Schema dict (``$ref`` should be resolved first).

    Returns:
        A new dict with all ``allOf`` keywords resolved.
    """
    return _walk_merge_allof(copy.deepcopy(schema))

def simplify_unions(schema: dict[str, Any]) -> dict[str, Any]:
    """Simplify ``anyOf``/``oneOf`` constructs.

    - Nullable pattern ``[{type: T}, {type: null}]`` → ``{type: T, nullable: true}``
    - Single-variant: unwrap.
    - Multi-variant with null: strip the ``{type: null}`` branch, keep remaining
      branches under the original keyword (``anyOf`` or ``oneOf``).

    Args:
        schema: A JSON Schema dict.

    Returns:
        A new dict with ``anyOf``/``oneOf`` simplified.
    """
    return _walk_simplify(copy.deepcopy(schema))

def sanitize(
    schema: dict[str, Any],
    *,
    strip_keys: set[str] | None = None,
) -> dict[str, Any]:
    """Strip unsupported schema keywords and validate ``required`` arrays.

    Args:
        schema: A JSON Schema dict.
        strip_keys: Additional keys to strip beyond
            :data:`UNSUPPORTED_SCHEMA_KEYS`.

    Returns:
        A new dict with unsupported keys removed and ``required`` arrays
        pruned so that ``required ⊆ properties.keys()`` at every level.
    """
    strip = UNSUPPORTED_SCHEMA_KEYS | (strip_keys or set())
    return _walk_sanitize(copy.deepcopy(schema), strip)

def flatten_schema(
    schema: dict[str, Any],
    *,
    strip_keys: set[str] | None = None,
) -> dict[str, Any]:
    """One-call full pipeline: resolve → merge → simplify → sanitize.

    Args:
        schema: A JSON Schema dict, possibly containing ``$ref``,
            ``allOf``, ``anyOf``, ``oneOf``, and unsupported keywords.
        strip_keys: Additional keys to strip beyond
            :data:`UNSUPPORTED_SCHEMA_KEYS`.

    Returns:
        A flattened, sanitized schema safe for LLM provider consumption.
    """
    result = resolve_refs(schema)
    result = _walk_merge_allof(result)  # skip redundant deepcopy
    result = _walk_simplify(result)
    strip = UNSUPPORTED_SCHEMA_KEYS | (strip_keys or set())
    result = _walk_sanitize(result, strip)
    return result

def iter_errors(
    instance: Any,
    schema: dict[str, Any] | bool,
    *,
    resolved: bool = False,
) -> list[SchemaErrorDetail]:
    """Validate *instance* against JSON Schema *schema* and return all errors.

    The schema is preprocessed: ``$ref`` pointers are resolved before
    validation.  Composition keywords (``allOf``, ``anyOf``, ``oneOf``,
    ``not``) are evaluated semantically, not merged.

    When validating many instances against the same schema, resolve once
    and pass ``resolved=True`` to skip redundant ``$ref`` resolution::

        schema = resolve_refs(raw_schema)
        for item in items:
            errors = iter_errors(item, schema, resolved=True)

    Args:
        instance: The data to validate.
        schema: A JSON Schema dict, or a boolean schema.
        resolved: If ``True``, skip ``$ref`` resolution (caller already
            called :func:`resolve_refs`).  Defaults to ``False`` because
            passing an unresolved schema with ``resolved=True`` silently
            skips ``$ref`` targets — the validator would ignore them and
            report no errors for the referenced sub-schemas.

    Returns:
        A list of :class:`SchemaErrorDetail`; empty if valid.
    """
    errors: list[SchemaErrorDetail] = []
    if isinstance(schema, bool):
        _validate_schema(instance, schema, errors, "", "")
        return errors
    effective = schema if resolved else resolve_refs(schema)
    _validate_schema(instance, effective, errors, "", "")
    return errors

def schema_validate(
    instance: Any,
    schema: dict[str, Any] | bool,
    *,
    resolved: bool = False,
) -> None:
    """Validate *instance* against JSON Schema *schema*.

    Args:
        instance: The data to validate.
        schema: A JSON Schema dict.
        resolved: If ``True``, skip ``$ref`` resolution (caller already
            called :func:`resolve_refs`).  Must not be set to ``True``
            unless the schema has been resolved — unresolved ``$ref``
            nodes would be silently ignored.

    Raises:
        SchemaValidationError: If validation fails, with all errors collected.
    """
    errors = iter_errors(instance, schema, resolved=resolved)
    if errors:
        raise SchemaValidationError(errors)