Imported Types Become Local Types
Use $import or $importdefs to copy published types into a local namespace, with absolute import URIs and explicit shadowing.
JSON Structure Blog
Welcome to the JSON Structure blog. Here we explore practical applications, dive deeper into features, and share insights about using JSON Structure effectively.
Definitions Are a Type Library
Use definitions as a case-sensitive namespace hierarchy for reusable types, including types that share a local name but not a meaning.
Choices Must Survive Code Generation
Code generation adapts a JSON Structure choice to the type system, serialization model, and artifact boundaries of each target.
Why Union Order Matters
Non-discriminated unions use first-match semantics, so branch order is part of the type contract rather than a cosmetic choice.
Inline Unions Need Explicit Discriminators
Model several concrete object variants that share an abstract base through $extends and use an explicit selector.
Tagged Unions Without Guesswork
In a JSON Structure tagged choice, a one-property wrapper names the selected payment method. Consumers select the variant from that tag instead of inferring it from the value's shape.
A Set Should Not Become a List by Accident
A JSON Structure set maps to native set-like types in several generated targets. Other projections require explicit uniqueness checks and an ordering policy when byte order matters.
Closed Objects and Open Maps
Use a closed object for schema-defined fields and a separate map for runtime-defined keys. A new object field requires a schema revision; a new map key does not.
Required, but in Which Combination?
The nested-array form of `required` selects exactly one complete property set. A contact record shows how JSON Structure evaluates the alternatives.
Named Positions in a Tuple
Named tuple positions preserve longitude and latitude in generated APIs while the JSON wire format remains an array.
Samples Are Evidence, Not a Contract
Structurize turns observed records into a useful JSON Structure draft. Domain knowledge then refines the inferred types, presence rules, and value domains.
Array, Set, or Map? Pick One
Array, set, and map encode different collection contracts. One playlist schema shows how order, uniqueness, and dynamic keys belong in the type.
Binary Data Has a Shape Too
JSON Structure defines binary values together with their text encoding, compression, and media type, so consumers know how to recover the payload.
Dates Are Types, Not String Formats
JSON Structure declares date, time, datetime, and duration as distinct types with RFC 3339 representations instead of treating them as decorated strings.
One Schema, Many Artifacts
Keep one JSON Structure schema as the source contract and project disposable documentation, protocols, database definitions, and code from it.
Decimal Is Not Double
JSON Structure separates exact base-10 decimal values from binary floating point and carries precision and scale in the data definition.
How Large Is Your Integer?
JSON Structure gives integers an explicit width and signedness, from int8 to uint128, while preserving large values safely in JSON strings.
A Schema Is More Than a Validator
JSON Structure defines the data model behind a JSON document, so the same Customer contract can drive validation, code, storage, and interchange.
Types and Units Still Don't Tell You What a Value Means
Two schemas can agree that a member is a double in metres and still describe water level above a tide gauge and height above an ellipsoid. An IETF Internet-Draft defines optional schema annotations for the missing semantic facts. A common reference-and-kind shape can bind coordinate systems, color profiles, weighting curves, code registers, spectral bands, and vector frames. Component lists also state which members supply ordered axes or channels. The annotations add no fields to conforming instance documents.
JSON Structure Defines Data Models
JSON Structure is a strongly typed schema language for data models that map cleanly to programming languages, databases, APIs, and JSON.
Structurize Turns Sample JSON into Typed Schemas
Structurize's json2s command infers JSON Structure schemas from JSON and JSONL samples for validation, code generation, and documentation.