JSON to Crystal Converter

From JSON sample to Crystal types

Hand-writing model classes from a JSON payload is transcription work: read a field, type a property, repeat eighty times, miss one. This page runs quicktype (the same engine behind the best-known generators) against your document, merging array elements to find the common shape and naming nested types from their keys.

Every field is declared with property, so the models are fully mutable; change the ones that should be read-only to getter once parsed. Root.from_json raises JSON::ParseException naming the failing property on drift — catch that specifically rather than a broad exception. The generated code needs no shard beyond the standard library's require "json".

How JSON values become Crystal types

Inference works from the values in your sample. Strings map to String, integers and decimals are told apart (228.99 becomes Float64, while 1 and 2 stay integral), true/false become the language's boolean, and an object such as "customer" becomes its own named type. The "items" array is typed as Array(Item) because every element shares the same keys — quicktype unifies the shapes of all array elements into one Item type.

Nulls are the one place inference needs your help: "phone": null carries no type information, so the field is emitted as Nil. If the real API sometimes sends a string there, include a sample where the field is populated (paste several documents merged into one array) and the generated type becomes the union of what it saw.

Pasting XML instead: how elements and attributes become Crystal types

The XML is parsed into a data model before inference (attributes included, text nodes named "text"), so the root element becomes a nested type: <order> is a field of type Order on the top-level Root rather than the top level itself. Child elements become fields, and repeated elements — the two <item> siblings — are collected into Array(Item) under an Items wrapper type that mirrors the <items> container.

Attributes and element text are typed differently, and this matters: element text is type-inferred, so <total>228.99</total> becomes Float64, while attribute values are kept as they were written — qty="1" and price="149.99" stay String in Crystal. Prefer element text for numeric data you want typed, or cast attribute values after decoding. One more trap: a single <item> would not be recognized as a list, so make sure repeated elements appear at least twice in the sample.

Annotations, nulls and nested arrays in the generated Crystal

Crystal classes include JSON::Serializable from the standard library, so from_json and to_json come for free with no shard to add. Renames use one annotation: a key such as customer-ref produces a JSON::Field annotation carrying key: "customer-ref" above a customer_ref property, while keys that are already valid identifiers get no annotation at all. Every field is declared with property, so the models are mutable. The same annotation accepts converter: and emit_null: if you need to reshape a single field without hand-writing the whole class.

A property whose only sampled value is null is typed Nil — the type with exactly one value — so it raises the moment a real string arrives. Add a document where the field carries a value and it becomes String?, shorthand for a String-or-Nil union that the compiler then forces you to handle. Properties missing from some of the merged samples become optional in the same way. An empty array is typed as an array of nullable JSON::Any, which means no element class was generated for it.

Nested objects become their own classes named from the key — Customer, Item — each including JSON::Serializable, so a single Root.from_json call walks the whole tree. Arrays of objects are typed Array(Item). Because Crystal checks these declarations at compile time and the parser enforces them at runtime, a payload that drifts raises JSON::ParseException naming the failing property instead of producing a half-built object. The usual two sample traps apply: one element hides optional fields, and an empty array generates no element class.