|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +--- |
| 4 | + |
| 5 | +# JSON Schema |
| 6 | + |
| 7 | +JSON Schema input support enables you to generate TypeScript models directly from JSON Schema documents. This is particularly useful when you have standalone JSON Schema files that define your data structures. |
| 8 | + |
| 9 | +## Supported Generators |
| 10 | + |
| 11 | +The JSON Schema input type supports the following generators: |
| 12 | + |
| 13 | +| Preset | JSON Schema | |
| 14 | +|-----------|---------| |
| 15 | +| [`models`](../generators/models.md) | ✅ | |
| 16 | +| [`custom`](../generators/custom.md) | ✅ | |
| 17 | + |
| 18 | +## Configuration |
| 19 | + |
| 20 | +### Basic Configuration |
| 21 | + |
| 22 | +```js |
| 23 | +export default { |
| 24 | + inputType: 'jsonschema', |
| 25 | + inputPath: './user-schema.json', |
| 26 | + language: 'typescript', |
| 27 | + generators: [ |
| 28 | + { |
| 29 | + preset: 'models', |
| 30 | + outputPath: './src/models' |
| 31 | + } |
| 32 | + ] |
| 33 | +}; |
| 34 | +``` |
| 35 | + |
| 36 | +### Advanced Configuration with Modelina Options |
| 37 | + |
| 38 | +```js |
| 39 | +export default { |
| 40 | + inputType: 'jsonschema', |
| 41 | + inputPath: './complex-schema.json', |
| 42 | + language: 'typescript', |
| 43 | + generators: [ |
| 44 | + { |
| 45 | + preset: 'models', |
| 46 | + outputPath: './src/models', |
| 47 | + options: { |
| 48 | + modelType: 'class', |
| 49 | + enumType: 'enum', |
| 50 | + mapType: 'record', |
| 51 | + rawPropertyNames: false, |
| 52 | + useJavascriptReservedKeywords: false |
| 53 | + }, |
| 54 | + renderers: [ |
| 55 | + { |
| 56 | + class: { |
| 57 | + property: ({ content, property }) => { |
| 58 | + return `/** ${property.property.description || 'Auto-generated property'} */\n${content}`; |
| 59 | + } |
| 60 | + } |
| 61 | + } |
| 62 | + ] |
| 63 | + } |
| 64 | + ] |
| 65 | +}; |
| 66 | +``` |
| 67 | + |
| 68 | +## Examples |
| 69 | + |
| 70 | +### Simple User Schema |
| 71 | + |
| 72 | +**Input: `user-schema.json`** |
| 73 | +```json |
| 74 | +{ |
| 75 | + "$schema": "http://json-schema.org/draft-07/schema#", |
| 76 | + "title": "User", |
| 77 | + "type": "object", |
| 78 | + "properties": { |
| 79 | + "id": { |
| 80 | + "type": "string", |
| 81 | + "format": "uuid" |
| 82 | + }, |
| 83 | + "name": { |
| 84 | + "type": "string" |
| 85 | + }, |
| 86 | + "email": { |
| 87 | + "type": "string", |
| 88 | + "format": "email" |
| 89 | + }, |
| 90 | + "age": { |
| 91 | + "type": "integer", |
| 92 | + "minimum": 0 |
| 93 | + } |
| 94 | + }, |
| 95 | + "required": ["id", "name", "email"] |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +**Configuration: `codegen.mjs`** |
| 100 | +```js |
| 101 | +export default { |
| 102 | + inputType: 'jsonschema', |
| 103 | + inputPath: './user-schema.json', |
| 104 | + language: 'typescript', |
| 105 | + generators: [ |
| 106 | + { |
| 107 | + preset: 'models', |
| 108 | + outputPath: './src/models' |
| 109 | + } |
| 110 | + ] |
| 111 | +}; |
| 112 | +``` |
| 113 | + |
| 114 | +**Generated Output: `src/models/User.ts`** |
| 115 | +```typescript |
| 116 | +export class User { |
| 117 | + private _id: string; |
| 118 | + private _name: string; |
| 119 | + private _email: string; |
| 120 | + private _age?: number; |
| 121 | + |
| 122 | + constructor(input: { |
| 123 | + id: string, |
| 124 | + name: string, |
| 125 | + email: string, |
| 126 | + age?: number, |
| 127 | + }) { |
| 128 | + this._id = input.id; |
| 129 | + this._name = input.name; |
| 130 | + this._email = input.email; |
| 131 | + this._age = input.age; |
| 132 | + } |
| 133 | + |
| 134 | + get id(): string { return this._id; } |
| 135 | + get name(): string { return this._name; } |
| 136 | + get email(): string { return this._email; } |
| 137 | + get age(): number | undefined { return this._age; } |
| 138 | + |
| 139 | + public marshal(): string { |
| 140 | + return JSON.stringify({ |
| 141 | + id: this.id, |
| 142 | + name: this.name, |
| 143 | + email: this.email, |
| 144 | + age: this.age, |
| 145 | + }); |
| 146 | + } |
| 147 | + |
| 148 | + public static unmarshal(json: string): User { |
| 149 | + const obj = JSON.parse(json); |
| 150 | + return new User(obj); |
| 151 | + } |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +### Complex Schema with Definitions |
| 156 | + |
| 157 | +**Input: `complex-schema.json`** |
| 158 | +```json |
| 159 | +{ |
| 160 | + "$schema": "http://json-schema.org/draft-07/schema#", |
| 161 | + "definitions": { |
| 162 | + "Address": { |
| 163 | + "type": "object", |
| 164 | + "properties": { |
| 165 | + "street": { "type": "string" }, |
| 166 | + "city": { "type": "string" }, |
| 167 | + "zipCode": { "type": "string" } |
| 168 | + }, |
| 169 | + "required": ["street", "city", "zipCode"] |
| 170 | + } |
| 171 | + }, |
| 172 | + "type": "object", |
| 173 | + "properties": { |
| 174 | + "person": { |
| 175 | + "type": "object", |
| 176 | + "properties": { |
| 177 | + "name": { "type": "string" }, |
| 178 | + "address": { "$ref": "#/definitions/Address" } |
| 179 | + }, |
| 180 | + "required": ["name"] |
| 181 | + } |
| 182 | + } |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +This will generate both `Person` and `Address` classes with proper type relationships. |
| 187 | + |
| 188 | +## File Format Support |
| 189 | + |
| 190 | +### JSON Format |
| 191 | +```json |
| 192 | +{ |
| 193 | + "$schema": "http://json-schema.org/draft-07/schema#", |
| 194 | + "type": "object", |
| 195 | + "properties": { |
| 196 | + "example": { "type": "string" } |
| 197 | + } |
| 198 | +} |
| 199 | +``` |
| 200 | + |
| 201 | +### YAML Format |
| 202 | +```yaml |
| 203 | +$schema: "http://json-schema.org/draft-07/schema#" |
| 204 | +type: object |
| 205 | +properties: |
| 206 | + example: |
| 207 | + type: string |
| 208 | +``` |
0 commit comments