specta_jsonschema/lib.rs
1//! [JSON Schema](https://json-schema.org) exporter and importer for [Specta](specta).
2//!
3//! This crate provides bidirectional conversion between Specta types and JSON Schema:
4//! - Export Specta types to JSON Schema (Draft 7, 2019-09, or 2020-12)
5//! - Import JSON Schema definitions as Specta DataTypes
6//!
7//! # Features
8//!
9//! - **Bidirectional conversion**: Export to JSON Schema and import from JSON Schema
10//! - **Multiple schema versions**: Support for Draft 7 (default), Draft 2019-09, and Draft 2020-12
11//! - **Serde integration**: Use `specta-serde` in userspace before export
12//! - **Flexible layouts**: Single file with `$defs` or separate files per type
13//! - **schemars ecosystem**: Compatible with the schemars crate for interoperability
14//!
15//! # Usage
16//!
17//! ## Exporting to JSON Schema
18//!
19//! ```ignore
20//! use serde::{Deserialize, Serialize};
21//! use specta::{Type, Types};
22//! use specta_jsonschema::{JsonSchema, SchemaVersion};
23//!
24//! #[derive(Serialize, Deserialize, Type)]
25//! #[serde(rename_all = "camelCase")]
26//! pub struct User {
27//! pub id: u32,
28//! pub name: String,
29//! pub email: Option<String>,
30//! }
31//!
32//! fn main() {
33//! let types = Types::default()
34//! .register::<User>();
35//!
36//! // Export to JSON Schema
37//! let schema = JsonSchema::default()
38//! .schema_version(SchemaVersion::Draft7)
39//! .export(&types, specta_serde::Format)
40//! .unwrap();
41//!
42//! println!("{}", schema);
43//! }
44//! ```
45//!
46//! ## With Serde Integration
47//!
48//! ```ignore
49//! use serde::{Deserialize, Serialize};
50//! use specta::{Type, Types};
51//! use specta_jsonschema::JsonSchema;
52//!
53//! #[derive(Serialize, Deserialize, Type)]
54//! #[serde(rename_all = "camelCase")]
55//! pub struct User {
56//! pub user_id: u32,
57//! #[serde(rename = "fullName")]
58//! pub name: String,
59//! }
60//!
61//! fn main() {
62//! let types = Types::default().register::<User>();
63//!
64//! JsonSchema::default()
65//! .export_to("./schema.json", &types, specta_serde::Format)
66//! .unwrap();
67//! }
68//! ```
69//!
70//! ## Importing from JSON Schema
71//!
72//! ```ignore
73//! use schemars::Schema;
74//! use specta_jsonschema::import::from_schema;
75//!
76//! let schema: Schema = serde_json::from_str(r#"{
77//! "type": "object",
78//! "properties": {
79//! "name": { "type": "string" },
80//! "age": { "type": "integer" }
81//! },
82//! "required": ["name"]
83//! }"#).unwrap();
84//!
85//! let datatype = from_schema(&schema).unwrap();
86//! ```
87//!
88//! ## Multiple Output Layouts
89//!
90//! ```ignore
91//! use specta_jsonschema::{JsonSchema, Layout};
92//!
93//! // Single file with all types in $defs
94//! JsonSchema::default()
95//! .layout(Layout::SingleFile)
96//! .export_to(
97//! "./schema.json",
98//! &types,
99//! specta_serde::Format,
100//! )
101//! .unwrap();
102//!
103//! // Separate file per type, organized by module
104//! JsonSchema::default()
105//! .layout(Layout::Files)
106//! .export_to(
107//! "./schemas/",
108//! &types,
109//! specta_serde::Format,
110//! )
111//! .unwrap();
112//! ```
113
114#![cfg_attr(docsrs, feature(doc_cfg))]
115#![doc(
116 html_logo_url = "https://github.com/specta-rs/specta/raw/main/.github/logo-128.png",
117 html_favicon_url = "https://github.com/specta-rs/specta/raw/main/.github/logo-128.png"
118)]
119#![allow(warnings)] // TODO: leaving this until it's implemented to avoid unnecessary warnings.
120
121mod error;
122pub mod import;
123mod json_schema;
124mod layout;
125mod primitives;
126mod schema_version;
127
128pub use error::Error;
129pub use json_schema::JsonSchema;
130pub use layout::Layout;
131pub use schema_version::SchemaVersion;
132
133// Legacy function - kept for backward compatibility
134#[deprecated(note = "Use import::from_schema instead")]
135pub fn to_ast(schema: &schemars::Schema) -> Result<specta::datatype::DataType, Error> {
136 import::from_schema(schema)
137}