Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Code generation

The primary benefit of a schema modeling system, is that you can consume this type information to generate code into multiple output formats. This is a common pattern in many languages, and is a great way to reduce boilerplate.

In the context of Rust, why use multiple disparate crates, each with their own unique implementations and #[derive] macros, just to generate some output. With Schematic, you can ditch all of these and use a single standardized approach.

Usage

To make use of the generator, import and instantiate our SchemaGenerator. This is typically done within a one-off main function that can be ran from Cargo.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
}

Adding types

From here, for every type that implements Schematic and you want to include in the generated output, call SchemaGenerator::add(). If you already have a Schema rather than a type, you can use the SchemaGenerator::add_schema() method instead.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
generator.add::<FirstConfig>();
generator.add::<SecondConfig>();
generator.add::<ThirdConfig>();
}

We’ll recursively add referenced and nested schemas for types that are added. No need to explicitly add all required types!

Schemas are keyed by name, so adding two different types that report the same one panics. Rendering both is impossible, and silently keeping one would leave every reference to the other pointing at the wrong type. Adding the same type twice is fine.

Generating output

From here, call SchemaGenerator::generate() to render the schemes with a chosen renderer to an output file of your choice. This method can be called multiple times, each with a different output file or renderer.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
generator.add::<FirstConfig>();
generator.add::<SecondConfig>();
generator.add::<ThirdConfig>();
generator.generate(PathBuf::from("output/file"), CustomRenderer::default())?;
generator.generate(PathBuf::from("output/another/file"), AnotherRenderer::default())?;
}

To keep the output in memory instead, such as to compare it, or write it somewhere other than a file, call SchemaGenerator::render(), which returns it as a string.

#![allow(unused)]
fn main() {
let output = generator.render(CustomRenderer::default())?;
}

Renderers

The following built-in renderers are available, but custom renderers can be created as well by implementing the SchemaRenderer trait.

Custom renderers

A custom renderer implements is_reference, which says whether a named type is rendered by reference, and render, which renders every collected schema. Each render_* method, one per type, defaults to an error naming the renderer and the type, so only the types a renderer supports need implementing.

#![allow(unused)]
fn main() {
use schematic::schema::{RenderResult, Schema, SchemaRenderer, StringType, StructType};

struct CustomRenderer;

impl SchemaRenderer for CustomRenderer {
	fn is_reference(&self, _name: &str) -> bool {
		false
	}

	fn render_string(&mut self, _string: &StringType, _schema: &Schema) -> RenderResult {
		Ok("string".into())
	}

	fn render_struct(&mut self, structure: &StructType, _schema: &Schema) -> RenderResult {
		// ...
	}

	fn render(&mut self, schemas: IndexMap<String, Schema>) -> RenderResult {
		// ...
	}
}
}

A tagged enum variant defaults to rendering as the struct serde writes for it, so a renderer only implements render_tagged to render each tag format itself.

A renderer whose types render to something other than a string, like the JSON schema renderer, sets the trait’s type parameter, as in SchemaRenderer<schemars::Schema>, while render always returns a string. A helper that takes any renderer is generic over both, like fn emit<O, R: SchemaRenderer<O>>(renderer: R).