Tables Are Projections, Not the Model
Treat SQL, Kusto, Parquet, and Iceberg outputs as target-specific projections of a JSON Structure model, with each preserved or lost source constraint recorded.
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.
Cardinality Belongs on the Relation
Declare `targettype` and `cardinality` on each relation, and declare `identity` on the target type instead of inferring any of them from names or foreign keys.
Using the unit and ucumUnit Keywords Together
Use `unit` for readable notation and `ucumUnit` for the case-sensitive UCUM expression used in computation and conversion.
Names Have Purposes
Use altnames purpose keys to give one canonical property distinct names for JSON, storage, generated code, and localized display.
Schema Imports Resolve Before Projection
Resolve JSON Structure imports into one closed type graph before projecting that graph into a target schema or generated program.
Imports Copy Definitions, Not Ambiguity
Resolve $import and $importdefs into local namespaces with rewritten internal references, deterministic shadowing, and standards-based URI handling.
Composition Combines Evaluation Results, Not Property Maps
Compare allOf, anyOf, oneOf, and not using one complete access request schema and the match count required by each operator.
if/then/else Without Changing the Type
Keep one stable address type and apply country-specific postal-code rules as conditional validation overlays with if, then, and else.
Every Projection Has a Semantic Budget
Treat Protocol Buffers, XSD, and ASN.1 outputs as format-specific projections whose preserved semantics must be tested explicitly.
Object Properties and Map Keys Need Different Pattern Rules
Apply patternProperties to named object extensions and patternKeys to dynamic map entries, while propertyNames and keyNames constrain the names themselves.
Conditional Property Requirements
Use dependentRequired when one property's presence requires companion fields, and core required when fields are mandatory for every object.
contains Is Not an Item Type
Use items to type every array member and contains to count members matching an additional condition.
Three Validation Gates for JSON Structure Builds
Make schema, input syntax, and instance validation separate build gates so malformed or invalid fulfillment data cannot pass unnoticed.
Separate Structure from Validation Policy
Separate structural facts used by generators from validation policies that narrow the accepted values.
Build a Schema Dialect Without Forking One
Compose a custom JSON Structure meta-schema from named add-ins and give processors an explicit, resolvable vocabulary contract.
Publishing and Selecting Features with $offers and $uses
A meta-schema advertises named vocabulary add-ins, and a schema document selects only the features it uses.
Generate Reference Documentation from JSON Structure
Generate reference documentation from JSON Structure while keeping the schema, not the rendered page, authoritative.
The Schema That Checks the Schema
Use JSON Structure meta-schemas to reject malformed schema documents before they can misdescribe any data.
Tensor Shape Does Not Define Tensor Meaning
Bind tensor indices to reference frames and declare component layout, variance, and rank-2 symmetry in the schema.
Identity and Relations Belong in the Schema
Declare object identity and typed relations with target types, cardinality, and scope instead of leaving foreign-key meaning in property names.
Wire Names Are Not Code Names
Serializer annotations preserve JSON wire names while generated identifiers follow each target language's naming and sanitization rules.
Units Give Numeric Values Meaning
Attach scientific units, UCUM codes, display symbols, SI prefixes, and currencies to numeric schemas so values can be interpreted correctly.
Enums Need Translation Too
Keep enum values stable while mapping them to external codes and localized labels with altenums, without changing the underlying contract.
One Property, Several Names
Keep one stable property in the schema while mapping it to JSON, database, Protobuf-style, and localized names with altnames and descriptions.
Compound Definitions Can Become Named Types
Structurize preserves local compound-definition references in Java, Go, and Rust, while C# and TypeScript lose part or all of that type identity.
Optional Add-ins in One Schema
Declare optional object add-ins with $offers; each instance selects the add-ins it uses with $uses.
Imported Types Become Local Types
Use $import or $importdefs to copy published types into a local namespace, with absolute import URIs and explicit shadowing.
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.