TypeScript Converters: 5 JSON Schema Type Flaws

Hand-Maintained Types vs. Generated Types: The 3 a.m. Production Bug

A backend engineer ships a payload change at 4 p.m. The TypeScript interface in the frontend repo still says `status: string`. The actual payload now sends `status: { code: number; label: string }`. At 3 a.m., a customer-facing dashboard crashes because `status.toUpperCase()` is not a function.

This is the cost of hand-maintained types in a schema-driven system. The fix is not "be more careful." The fix is to stop writing types by hand and start generating them from your JSON schemas. But generation itself is littered with pitfalls—poorly configured converters produce types that compile, pass review, and still misrepresent reality.

This guide is for teams building API contracts with JSON Schema who need their TypeScript types to stay mechanically in sync. We will walk through the most common mistakes and their concrete fixes.

Schema Discipline: Vague Schemas vs. Strict Schemas

The Pitfall: Trusting Loose Schemas

A schema like this is technically valid JSON Schema, but it produces useless TypeScript:

```json { "type": "object", "properties": { "id": {}, "metadata": {} } } ```

Most TypeScript converters will emit `id: any` and `metadata: any`. You have generated a type that provides zero type safety. The converter did its job. The schema failed to do its job.

The Fix: Treat Schemas as Production Code

Every property needs an explicit type. Every object needs `additionalProperties: false` unless you genuinely want an open-ended map. A strict schema:

```json { "type": "object", "additionalProperties": false, "required": ["id", "metadata"], "properties": { "id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": false, "properties": { "createdAt": { "type": "string", "format": "date-time" } }, "required": ["createdAt"] } } } ```

This produces a TypeScript type you can actually rely on. The rule is simple: **if your schema is vague, your generated types are fiction.** No converter can add safety that the schema does not contain.

Tool Selection: One-Off Conversion vs. Sustained Pipeline

The Pitfall: Using Browser-Based Converters for Production Types

Pasting a schema into a web-based JSON-to-TypeScript converter is fine for a quick prototype. It is a serious problem for a production codebase. The output is unversioned, unreviewed, and detached from the source schema. When the schema changes—and it will—nobody remembers to regenerate.

A real example: a team managing a 47-field customer payload schema used a paste-and-copy workflow for six months. By month four, the generated TypeScript type was missing three fields that had been added to the schema. Two of those fields were required. The frontend silently ignored them because the type said they did not exist.

The Fix: Build a Generation Script

Use a tool like `json-schema-to-typescript` or `quicktype` inside a script that runs in your build pipeline. Pin the version. Commit the output. Make regeneration a single command:

```bash npx json-schema-to-typescript src/schemas/customer.json -o src/types/customer.ts ```

Better yet, wire it into your CI so that if a schema changes without a corresponding type file update, the build fails. The goal is to make drift impossible to merge, not just unlikely.

Naming and Inference: Descriptive IDs vs. Cryptic Output

The Pitfall: Letting the Converter Name Your Types

When a converter encounters an anonymous nested object, it generates names based on heuristics. You get types like `CustomerPropertiesMetadataItems` or `RootObject`. These names propagate through your codebase. They appear in autocomplete suggestions, error messages, and pull request diffs. They make the codebase harder to read and harder to trust.

The Fix: Use `$id` and `title` Explicitly

JSON Schema supports `$id` and `title` for a reason. Use them on every schema and every meaningful sub-schema:

```json { "$id": "customer", "title": "Customer", "type": "object", "properties": { "billingAddress": { "title": "Address", "$id": "address", "type": "object", "properties": { "street": { "type": "string" } } } } } ```

Now the converter emits `Customer` and `Address` instead of `RootObject` and `CustomerPropertiesBillingAddress`. Clean names reduce cognitive load. They also make grep useful—if you search for `Address`, you find the type, the schema, and every usage in one pass.

Optional, Nullable, and Undefined: The Three-Headed Beast

The Pitfall: Confusing Absence with Null

This is the single most common bug in generated TypeScript types. In JSON Schema, a property that is not in `required` is optional—it may be absent. A property with `"type": ["string", "null"]` is nullable—it may be present but null. These are different concepts. Many converters conflate them or handle them inconsistently.

Consider this schema:

```json { "type": "object", "properties": { "middleName": { "type": ["string", "null"] } }, "required": ["middleName"] } ```

`middleName` is required (always present) but nullable (can be `null`). The correct TypeScript is `middleName: string | null`. But some converters produce `middleName?: string | null`, which incorrectly signals the field can be missing. Others produce `middleName: string | undefined | null`, introducing a third state that the JSON payload can never actually produce.

The Fix: Configure Your Converter and Audit the Output

If you use `json-schema-to-typescript`, set these options in your config:

```json { "strictNullChecks": true, "noAdditionalProps": true } ```

Then audit the output for every nullable field. The mapping should be:

- **Absent (not in `required`)** → `field?: string` - **Nullable (type includes `null`)** → `field: string | null` - **Both** → `field?: string | null`

If your converter cannot produce this mapping correctly, switch converters. This is not a cosmetic issue. A type that says a field is optional when it is actually required will cause runtime crashes. A type that says a field is required when it is optional will cause unnecessary guard clauses and dead code branches.

CI Integration: Manual Regeneration vs. Automated Drift Detection

The Pitfall: "Remember to Regenerate" as a Workflow

Any process that depends on a developer remembering to do something will eventually fail. A schema gets updated in a shared package. The consumer app's types are not regenerated. The build passes because the old types are still valid TypeScript. The bug ships.

The Fix: Fail the Build on Drift

Add a CI step that regenerates types and checks for changes:

```bash npm run generate-types git diff --exit-code src/types/ ```

If the generated files differ from what is committed, the step fails. The developer must regenerate and commit the updated types. This turns type drift from a silent failure into a loud, blocking one.

For teams consuming schemas from a separate repository, publish the generated `.ts` files as part of the schema package. Consumers should import types from the package, not generate their own. This ensures every consumer has the same types, derived from the same schema, at the same version.

The Underlying Principle

Every pitfall above shares a root cause: treating type generation as a conversion task rather than a contract enforcement mechanism. A TypeScript converter is not a translator. It is a compiler. Its input is a schema, its output is type safety, and its quality is entirely determined by the discipline of the input.

Strict schemas. Named types. Correct null handling. CI-enforced regeneration. Get these four things right and your generated TypeScript types will be more accurate, more durable, and more trustworthy than anything a human could maintain by hand.