You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Python code generator that transforms [JSON Schema](https://json-schema.org/) definitions into Python [`@validataclass`](https://github.com/binary-butterfly/validataclass)-decorated dataclasses or plain `@dataclass` classes, along with Enum classes.
3
+
A Python code generator that transforms [JSON Schema](https://json-schema.org/) definitions into Python [`@validataclass`](https://github.com/binary-butterfly/validataclass)-decorated dataclasses, plain `@dataclass` classes, or [Pydantic](https://docs.pydantic.dev/)`BaseModel` classes, along with Enum classes.
4
+
4
5
5
6
## Features
6
7
7
8
- Parses JSON Schema files, including `$ref` references across multiple files and remote schemas (HTTP)
8
-
-Generates `@validataclass`-decorated dataclasses with typed validator fields, or plain `@dataclass` classes
-[Ruff](https://docs.astral.sh/ruff/) (post-processing of generated files)
22
-
-[validataclass](https://github.com/binary-butterfly/validataclass) (used in generated code, not needed for `@dataclass` output)
24
+
-[validataclass](https://github.com/binary-butterfly/validataclass) (used in generated code, only needed for `validataclass` output)
25
+
-[Pydantic](https://docs.pydantic.dev/) (used in generated code, only needed for `pydantic` output)
26
+
23
27
24
28
## Installation
25
29
30
+
```bash
31
+
uv add schema2validataclass
32
+
```
33
+
34
+
Or with pip:
35
+
26
36
```bash
27
37
pip install schema2validataclass
28
38
```
29
39
40
+
30
41
## Usage
31
42
32
43
```bash
@@ -52,9 +63,24 @@ This reads the schema, recursively resolves all `$ref` references to other schem
52
63
- One Python file per `enum` type (e.g. `day_enum.py`)
53
64
- One Python file per `object` type (e.g. `closure_information_input.py`)
54
65
55
-
### Generated output example
56
66
57
-
Given a JSON Schema object with optional boolean and string fields, the generator produces:
67
+
### Generated output examples
68
+
69
+
Given a JSON Schema object with optional boolean and string fields, the generator produces different output depending on the configured `output_format`.
70
+
71
+
For enum schemas, the output is the same across all formats:
72
+
73
+
```python
74
+
from enum import Enum
75
+
76
+
classDayEnum(Enum):
77
+
MONDAY="monday"
78
+
TUESDAY="tuesday"
79
+
WEDNESDAY="wednesday"
80
+
```
81
+
82
+
83
+
#### `validataclass` output (default)
58
84
59
85
```python
60
86
from validataclass.validators import StringValidator, BooleanValidator
@@ -69,29 +95,17 @@ class ClosureInformationInput(ValidataclassMixin):
This is the default output format. It uses the [`validataclass`](https://github.com/binary-butterfly/validataclass) library for runtime validation. Optional fields use `UnsetValue` by default (configurable via `unset_value_output`). Classes optionally inherit from `ValidataclassMixin` (configurable via `set_validataclass_mixin`).
82
99
83
-
### `@dataclass` output
84
100
85
-
Instead of generating `@validataclass`-decorated classes, the generator can produce plain Python `@dataclass`classes. This is useful when you don't need runtime validation and want lightweight data containers with no external dependencies beyond the standard library.
101
+
#### `dataclass`output
86
102
87
103
Set `output_format: dataclass` in your config file (see [Configuration](#configuration) below):
88
104
89
105
```yaml
90
106
output_format: dataclass
91
107
```
92
108
93
-
The same schema that produces the validataclass example above generates:
94
-
95
109
```python
96
110
from dataclasses import dataclass
97
111
@@ -102,14 +116,27 @@ class ClosureInformationInput:
102
116
closedFrom: str | None = None
103
117
```
104
118
105
-
Key differences from `@validataclass` output:
119
+
This produces plain Python `@dataclass` classes with no external dependencies. Optional fields default to `None`, required fields are bare type annotations. The `set_validataclass_mixin` and `unset_value_output` config options have no effect.
120
+
121
+
122
+
#### `pydantic` output
123
+
124
+
Set `output_format: pydantic` in your config file:
- Fields are plain type annotations without validators
109
-
- Optional fields default to `None` instead of `UnsetValue`
110
-
- Required fields are bare type annotations (e.g. `name: str`)
111
-
- No dependency on the `validataclass` package
112
-
- `set_validataclass_mixin`and `unset_value_output` config options have no effect
130
+
```python
131
+
from pydantic import BaseModel
132
+
133
+
class ClosureInformationInput(BaseModel):
134
+
permananentlyClosed: bool | None = None
135
+
temporarilyClosed: bool | None = None
136
+
closedFrom: str | None = None
137
+
```
138
+
139
+
This produces [Pydantic V2](https://docs.pydantic.dev/) `BaseModel` classes. Constraints like `minimum`, `maximum`, `minLength`, `maxLength`, and `pattern` are rendered using `Annotated[type, Field(...)]`. Properties that conflict with Python reserved words are renamed with a trailing underscore and a `@model_validator(mode='before')` is generated to map the original names. The `set_validataclass_mixin` and `unset_value_output` config options have no effect.
113
140
114
141
### Loop detection
115
142
@@ -127,6 +154,7 @@ Loop detection is enabled by default. To disable it:
127
154
detect_looping_references: false
128
155
```
129
156
157
+
130
158
## Configuration
131
159
132
160
The generator can be configured via a YAML file passed with the `-c` / `--config` flag:
| `detect_looping_references` | `true` | Detect and remove circular `$ref` chains to prevent import cycles |
196
+
| `post_processing` | `[ruff-format, ruff-check]` | Post-processing steps to run on generated files |
197
+
| `ignore_references` | `[]` | List of `$ref` target URIs to ignore (suffix match). Properties referencing these are removed from their parent. |
198
+
| `ignore_paths` | `[]` | List of schema paths to ignore (suffix match). The property at the given path is removed during loading. |
199
+
| `renamed_properties` | Python keywords | List of property names that get a trailing `_` to avoid conflicts. Defaults to all Python reserved keywords. |
200
+
| `header` | Copyright header | Python file header prepended to every generated file |
201
+
202
+
203
+
### `ignore_references` vs `ignore_paths`
204
+
205
+
Both options remove properties from the generated output, but they match differently:
206
+
207
+
- **`ignore_references`** matches the **target** of a `$ref`. For example, `third_schema.json#/definitions/IgnoredObject` removes every property that references that definition, regardless of where the property appears.
208
+
- **`ignore_paths`** matches the **location** of a property in the schema. For example, `second_schema.json#/definitions/SecondObject/properties/IgnoredObject` removes only that specific property from `SecondObject`, even if other objects also reference the same definition.
209
+
210
+
Both use suffix matching, so you can omit leading path components.
0 commit comments