JSON Schema to TypeScript Converter

JSON Schema and TypeScript Solve Different Problems

JSON Schema describes constraints that can be evaluated against data at runtime. TypeScript describes values to the compiler while you develop, and its types are erased from normal JavaScript output. Converting a schema is therefore a translation of the parts that TypeScript can express, not a replacement for schema validation.

A property with type: "string" maps naturally to string. A rule such as minLength: 3, pattern, minimum, or most format checks does not have an equivalent ordinary TypeScript property type. Those rules stay visible as warnings because the static shape is only part of the contract.

How Common Schema Keywords Map

Required, Optional, and Nullable Are Separate Ideas

In JSON Schema, required controls whether an object member must exist. It does not make the value non-null. A field can be required and still allow null when its schema includes the null type. Conversely, an optional property can have a non-null string type when present.

Schema
{
  "type": "object",
  "required": ["name", "nickname"],
  "properties": {
    "name": { "type": "string" },
    "nickname": { "type": ["string", "null"] },
    "bio": { "type": "string" }
  }
}

TypeScript
interface GeneratedType {
  name: string;
  nickname: string | null;
  bio?: string;
  // an index signature may also appear when extra keys are modeled
}

When a schema omits required, JSON Schema treats the declared properties as optional. The corresponding option is enabled by default. Turning it off is an explicit generator override, not standard JSON Schema behavior.

Local $ref Resolution and Reference Boundaries

References beginning with a local JSON Pointer such as #/$defs/Address or #/definitions/User are resolved against the schema document you pasted. JSON Pointer escaping for ~0 and ~1 is handled when walking the document.

External references such as another file or HTTPS URL are not fetched. A direct recursive reference back to the root can map to the generated root type, while recursive local-definition patterns that cannot be emitted safely use unknown or any at the unsupported recursive edge. Those fallbacks appear in the warning panel before you copy the code.

Draft 2020-12 also allows sibling keywords beside $ref and introduces dynamic references. Those evaluator semantics are not reproduced by a plain TypeScript declaration, so unsupported or partially represented cases are reported instead of being treated as equivalent validation logic.

Tuple Schemas Depend on the Draft

Draft 2020-12 uses prefixItems for positional tuple entries and items for any remaining entries. For example, two prefix items with items: false describe a fixed two-element tuple. If items is omitted or true, additional values remain allowed.

Older schema drafts used an array in items for tuple positions and additionalItems for the tail. That older shape is recognized as a compatibility path and is called out so the draft-specific behavior does not disappear in generated code.

additionalProperties Is Not the Same as an Exact TypeScript Object

JSON Schema allows additional object names by default. With Add index signature selected, that openness appears as a string index signature. If additionalProperties contains its own schema, that value type is included too.

There is no perfect ordinary TypeScript equivalent for “these known properties have their own types, while every other string key must satisfy another schema.” An index signature must also be compatible with the declared properties, so the generated signature may be broader than the JSON Schema rule. That widening is reported because it changes what the static type appears to allow.

Likewise, additionalProperties: false is a runtime validation rule. TypeScript performs excess-property checks in some object-literal situations, but its structural type system does not universally guarantee JSON Schema-style object exactness after values flow through variables or other types.

Why Camel-Casing Property Names Is Flagged

A schema property named user-id describes a JSON key literally named user-id. Changing the generated property to userId is not only formatting; it changes the shape being described. Keep Preserve when the type is meant to model parsed JSON directly. Use camel case only when another layer in your application transforms the keys, and review collision warnings such as two source keys that normalize to the same name.

Validation Keywords That Stay at Runtime

TypeScript can represent broad shapes, unions, intersections, optional members, tuples, and literal values, but ordinary types do not validate most JSON Schema assertions. Examples include numeric limits, string length and regex patterns, array uniqueness and size, conditional schemas, dependencies, property-name patterns, content annotations, and unevaluated-item/property rules.

Boolean Schemas: true and false

JSON Schema permits a schema itself to be the boolean value true or false. A true schema accepts every instance, so it maps to the selected fallback type—unknown by default. A false schema accepts no instance and maps naturally to TypeScript never.

Before generated types go into a codebase

1. Validate that the source document is the JSON Schema draft and dialect your system actually uses.
2. Generate TypeScript with property names preserved unless your runtime transforms the data.
3. Read every warning, especially references, composition keywords, additional properties, and validation-only rules.
4. Compile the generated declarations in the real project with its actual TypeScript settings.
5. Keep runtime JSON Schema validation at trust boundaries such as API input, config loading, queues, files, or third-party responses.
6. Regenerate or diff the TypeScript when the authoritative schema changes so the static model does not drift.

The two specifications meet at different boundaries

Tuple behavior, $ref siblings, vocabularies, and runtime assertions follow the JSON Schema Draft 2020-12 documents. Local pointer references use the escaping rules from RFC 6901. Once a schema becomes TypeScript, assignability, optional properties, index signatures, and excess-property checks follow the TypeScript object-type rules, which are intentionally not the same thing as runtime JSON Schema validation.

Keep the runtime contract beside the generated types