12 releases (6 breaking)
0.7.0 | Sep 16, 2021 |
---|---|
0.6.0 | Mar 14, 2021 |
0.5.0 | Dec 25, 2020 |
0.4.1 | Sep 8, 2020 |
0.1.1 | Apr 21, 2017 |
#1061 in Encoding
144 downloads per month
105KB
2.5K
SLoC
json_typegen - Rust types from JSON samples
json_typegen is a collection of tools for generating types from JSON samples for Rust, Kotlin and TypeScript. I.e. you give it some JSON, and it gives you the type definitions necessary to use that JSON in a program.
There are three interfaces to this code generation logic:
Procedural macro
In Rust the code generation can be used straight from the program you are making, with a procedural macro.
For those familiar with F#, the procedural macro json_typegen!
works as
a type provider for JSON in Rust. It was inspired by and uses the same kind
of inference algorithm as F# Data.
As an example, the below code generates the type Point
based on an inline sample.
use json_typegen::json_typegen;
json_typegen!("Point", r#"{ "x": 1, "y": 2 }"#);
fn main() {
let mut p: Point = serde_json::from_str(r#"{ "x": 3, "y": 5 }"#).unwrap();
println!("deserialized = {:?}", p);
p.x = 4;
let serialized = serde_json::to_string(&p).unwrap();
println!("serialized = {}", serialized);
}
The following crate dependencies are necessary for this example to work:
[dependencies]
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"
json_typegen = "0.7"
The sample json can also come from local or remote files:
json_typegen!("Point", "json_samples/point.json");
json_typegen!("Point", "http://example.com/someapi/point.json");
The code generation can also be customized:
json_typegen!("Point", "http://example.com/someapi/point.json", {
use_default_for_missing_fields,
"/foo/bar": {
use_type: "map"
}
});
For the details on configuration, see the relevant documentation.
Conditional compilation
To avoid doing a HTTP request per sample used for every build you can use conditional compilation to only check against remote samples when desired:
#[cfg(not(feature = "online-samples"))]
json_typegen!("pub Point", r#"{ "x": 1, "y": 2 }"#);
#[cfg(feature = "online-samples")]
json_typegen!("pub Point", "https://typegen.vestera.as/examples/point.json");
And in Cargo.toml:
[features]
online-samples = []
You can then verify that remote samples match your expectations in e.g. CI builds as follows:
cargo check --features "online-samples"
Command line interface
The crate json_typegen_cli
provides a CLI to the same code generation as the
procedural macro uses internally. This provides a useful migration path if you
at some point need to customize the generated code beyond what is practical
through macro arguments.
For details on installation and usage see its readme.
Web interface
For simple testing and one-time use there is also a WebAssembly-powered
web interface hosted at https://typegen.vestera.as/.
Source code in json_typegen_web
.
Creating your own type provider crate
Both procedural macros and the shape inference algorithm are actually very simple. To learn/copy the algorithm you can look at this stripped-down version(< 200 lines).
License
This project is dual licensed, under either the Apache 2.0 or the MIT license, at your option.
Dependencies
~6–13MB
~172K SLoC