---
title: jsonschema
description: "Convert JSON Schema to Python types with validation."
---

# `marvin.utilities.jsonschema`
Convert JSON Schema to Python types with validation.

The jsonschema_to_type function converts a JSON Schema into a Python type that can be used
for validation with Pydantic. It supports:

- Basic types (string, number, integer, boolean, null)
- Complex types (arrays, objects)
- Format constraints (date-time, email, uri)
- Numeric constraints (minimum, maximum, multipleOf)
- String constraints (minLength, maxLength, pattern)
- Array constraints (minItems, maxItems, uniqueItems)
- Object properties with defaults
- References and recursive schemas
- Enums and constants
- Union types

Example:
    ```python
    schema = {
        "type": "object",
        "properties": {
            "name": {"type": "string", "minLength": 1},
            "age": {"type": "integer", "minimum": 0},
            "email": {"type": "string", "format": "email"}
        },
        "required": ["name", "age"]
    }

    # Name is optional and will be inferred from schema's "title" property if not provided
    Person = jsonschema_to_type(schema)
    # Creates a validated dataclass with name, age, and optional email fields
    ```

## Constants

### `FORMAT_TYPES`
```python
FORMAT_TYPES = {'date-time': datetime, 'email': EmailStr, 'uri': AnyUrl, 'json': Json}
```

## Classes

### `JSONSchema`
```python
class JSONSchema()
```

## Functions

### `create_array_type`
```python
def create_array_type(schema: Mapping[str, Any], schemas: Mapping[str, Any]) -> type | Annotated[Any, ...]
```
Create list/set type with optional constraints.

### `create_dataclass`
```python
def create_dataclass(schema: Mapping[str, Any], name: str | None = None, schemas: Mapping[str, Any] | None = None) -> type
```
Create dataclass from object schema.

### `create_enum`
```python
def create_enum(name: str, values: list[Any]) -> type | Enum
```
Create enum type from list of values.

### `create_field_with_default`
```python
def create_field_with_default(field_type: type, default_value: Any, schema: dict[str, Any]) -> Any
```
Create a field with simplified default handling.

### `create_numeric_type`
```python
def create_numeric_type(base: Type[Union[int, float]], schema: Mapping[str, Any]) -> type | Annotated[Any, ...]
```
Create numeric type with optional constraints.

### `create_string_type`
```python
def create_string_type(schema: Mapping[str, Any]) -> type | Annotated[Any, ...]
```
Create string type with optional constraints.

### `get_default_value`
```python
def get_default_value(schema: dict[str, Any], prop_name: str, parent_default: dict[str, Any] | None = None) -> Any
```
Get default value with proper priority ordering.
1. Value from parent's default if it exists
2. Property's own default if it exists
3. None

### `hash_schema`
```python
def hash_schema(schema: Mapping[str, Any]) -> str
```
Generate a deterministic hash for schema caching.

### `jsonschema_to_type`
```python
def jsonschema_to_type(schema: Mapping[str, Any], name: str | None = None) -> type
```
Convert JSON schema to appropriate Python type with validation.

Args:
    schema: A JSON Schema dictionary defining the type structure and validation rules
    name: Optional name for object schemas. Only allowed when schema type is "object".
        If not provided for objects, name will be inferred from schema's "title"
        property or default to "Root".

Returns:
    A Python type (typically a dataclass for objects) with Pydantic validation

Raises:
    ValueError: If a name is provided for a non-object schema

Examples:
    Create a dataclass from an object schema:
    ```python
    schema = {
        "type": "object",
        "title": "Person",
        "properties": {
            "name": {"type": "string", "minLength": 1},
            "age": {"type": "integer", "minimum": 0},
            "email": {"type": "string", "format": "email"}
        },
        "required": ["name", "age"]
    }

    Person = jsonschema_to_type(schema)
    # Creates a dataclass with name, age, and optional email fields:
    # @dataclass
    # class Person:
    #     name: str
    #     age: int
    #     email: str | None = None
    ```
    Person(name="John", age=30)

    Create a scalar type with constraints:
    ```python
    schema = {
        "type": "string",
        "minLength": 3,
        "pattern": "^[A-Z][a-z]+$"
    }

    NameType = jsonschema_to_type(schema)
    # Creates Annotated[str, StringConstraints(min_length=3, pattern="^[A-Z][a-z]+$")]

    @dataclass
    class Name:
        name: NameType
    ```

### `merge_defaults`
```python
def merge_defaults(data: Mapping[str, Any], schema: Mapping[str, Any], parent_default: Mapping[str, Any] | None = None) -> dict[str, Any]
```
Merge defaults with provided data at all levels.

### `resolve_ref`
```python
def resolve_ref(ref: str, schemas: Mapping[str, Any]) -> Mapping[str, Any]
```
Resolve JSON Schema reference to target schema.

### `sanitize_name`
```python
def sanitize_name(name: str) -> str
```
Convert string to valid Python identifier.

### `schema_to_type`
```python
def schema_to_type(schema: Mapping[str, Any], schemas: Mapping[str, Any]) -> type
```
Convert schema to appropriate Python type.

---

**Parent Module:** [`utilities`](marvin-utilities)
