TypeScript interface type definition automatic generation tool from JSON | ZeroTools

When extracting TypeScript interfaces from JSON data, this tool infers types based on the data types of a single input JSON sample.

The data structure of JSON basically consists of key-value pairs, but the static type definitions required on the TypeScript side must cover all variations of values expected during operation.

In the implementation of this tool, a judgment using the JavaScript typeof operator is performed on the input value, and primitive types such as string for strings, number for numbers, and boolean for booleans are simply assigned.

However, because this inference process is based strictly on a single input example, it is impossible to guess the existence of other data types not present in the JSON.

For example, if the value of a certain key is a number in the input example, even if there is a possibility that the key may be sent as a string in actual system operation, the tool uniquely determines and outputs it as a number type.

This is not type validation. Unlike definition files with strict constraints such as JSON Schema, this is an auxiliary mechanism that maps the structure readable from the sample to TypeScript syntax, so developers need to view the output code as a starting point for early development rather than trusting it as-is.

When objects are deeply nested within JSON data, this tool does not define them as inline structures, but rather splits and outputs them as independent interfaces.

When encountering a nested element, it dynamically generates a new type name by concatenating the parent interface name and the capitalized first letter of the corresponding key.

If the root name is UserResponse and there is an object with the key profile inside it, a type named UserResponseProfile is created, and the root property references that new type.

In this name generation process, measures are taken for cases where the key name contains symbols such as hyphens or spaces. Property names that are valid bare identifiers are preserved as-is, while keys containing symbols, spaces, or leading digits are quoted using JSON.stringify (for example, "user-id": string; or "123": number;) so that valid TypeScript interface syntax is always maintained.

For interface and type names, characters other than ASCII alphanumeric letters, underscores, and dollar signs are removed, and an underscore is prepended if the name begins with a digit or matches a TypeScript reserved keyword.

If a normalized name becomes empty, RootObject is used as the fallback, and base names are truncated to 64 characters. When duplicate interface names occur across different parts of the structure, the generator resolves collisions by appending incremental numeric suffixes (such as 2, 3), and parent properties consistently reference the allocated unique interface names.

In the type extraction process for array data, all elements contained within the array are scanned to collect and merge comprehensive type information.

If the array contains object elements, all fields across all observed objects are merged into a single interface named with Item appended to the array context (such as UserResponseLoginAttemptsItem).

For arrays containing primitives or mixed values, elements are inspected across the full sample array to derive an accurate union array representation.

When the root JSON value is a primitive, null, or empty array, the generator outputs a root export type alias (such as export type RootObject = unknown[]; or export type RootObject = string;), while object arrays generate the root type alias alongside the nested Item interface declarations.

When multiple different primitive types or object types are mixed within an array, the collected types are merged with pipe symbols into union arrays, such as (string | number)[].

Null values within data structures are preserved explicitly as null (yielding unions like string | null) rather than being collapsed into unknown or any.

Empty arrays where element types cannot be determined from the sample are typed as unknown[], and empty objects are output as empty interfaces.

Because generated types reflect only the provided sample instance, developers should manually inspect any unknown[] or null definitions and adjust them against formal backend specifications.

When handling JSON data such as API responses, cases frequently occur where specific items may or may not be present depending on request conditions or server-side states.

The optional Make all attributes optional switch feature of this tool provides a mechanism to uniformly append a question mark to the end of all property names of the generated interfaces.

When this switch is enabled, even essential items in the data model are treated as optional, constructing flexible type definitions where all items can be undefined.

Within arrays of objects, the core inference logic automatically compares all elements in the sample: any property that is absent from one or more observed objects is automatically marked optional with a question mark, while types present across objects are merged as unions.

The Make all attributes optional switch supplements this by forcing every property across the entire output to be optional, which is particularly helpful when modeling PATCH payloads, partial response bodies, or query filters where any field might be omitted.

However, the inference remains strictly sample-based and cannot detect fields absent from all elements of the provided input.

If you want to perform strict property existence checks in a TypeScript environment, the appropriate operational procedure is to first inspect whether sample arrays already provide partial occurrences to trigger automatic optional properties.

You can leave the switch disabled to preserve required fields identified in the sample, and then manually append question marks only to properties that can be missing under wider operational conditions not represented in the sample text.

On the operation screen of this tool, when a JSON string is pasted into the input text area, the TypeScript code extraction process is executed synchronously immediately upon detecting a change in the input content.

Because this conversion process is performed synchronously on the main thread within the browser, it provides a mechanism to easily generate type definitions on hand without involving communication processing to external servers.

The converter enforces computational thresholds to bound processing work: the raw input text is capped at 100,000 UTF-16 code units prior to JSON.parse, whereas structural constraints—capping object nesting at a maximum depth of 32 (counting the root level as 1), traversal at 20,000 nodes, and declarations at 256 interfaces or type aliases—are evaluated after parsing during structural traversal and type inference.

These limits constrain workload but do not guarantee responsiveness or prevent memory exhaustion across every client environment.

Because the UI expects valid JSON text, inputs cannot syntactically represent NaN, Infinity, or cyclic graphs directly; however, numeric literals that overflow standard float ranges during parsing (such as 1e400) produce non-finite values and are rejected with explicit errors.

Users should extract representative payload samples and manually review generated interfaces against full API specifications.

The extracted TypeScript code adopts a structured output order where the root interface or type alias is placed first, followed by nested child interfaces emitted in depth-first traversal order.

The generator emits declarations sequentially without performing cross-module hierarchy analysis or multi-file code splitting. Consequently, developers working with larger schema outputs must manually organize the generated declarations into appropriate domain files, manage naming imports, and verify compatibility against their production build pipelines and strict compiler settings.

A clear gap exists in the resolution of expressible meaning between the JSON data format and TypeScript interfaces. JSON is merely a serialization format for data transfer, and it has no means to express whether a number contained within it is an integer representing an age or a floating-point number representing a monetary amount, or whether a string corresponds to a specific date format or an enum value.

On the other hand, while literal types or more strict aliases can be defined in the TypeScript type system, the code generated by this tool is simply mapped from the superficial characteristics of JSON to the most basic primitive types.

Also, the output interfaces are merely descriptions to assist static analysis during development, and do not guarantee or verify whether JSON data acquired from the outside completely matches the structure of that interface in the execution environment after compilation.

Even if unknown properties are added or values of unexpected types are mixed in actual API communication, TypeScript type information alone cannot prevent runtime crashes.

The type definitions output from this implementation are nothing more than a hypothetical model derived from a single sample data.

Building upon this code, it is only after proceeding through comparison with API specification documents and the implementation of validation using runtime type verification libraries that a robust, type-safe system can be constructed.