rschema 0.2.0

A json-schema generator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Rschema   [![Crates Badge]][crates.io] [![Docs Badge]][docs.rs] [![License: Apache]][Apache 2.0] [![License: MIT]][MIT]

[Crates Badge]: https://img.shields.io/crates/v/rschema.svg
[crates.io]: https://crates.io/crates/rschema
[Docs Badge]: https://docs.rs/rschema/badge.svg
[docs.rs]: https://docs.rs/rschema
[License: Apache]: https://img.shields.io/badge/License-Apache_2.0-blue.svg
[Apache 2.0]: https://opensource.org/licenses/Apache-2.0
[License: MIT]: https://img.shields.io/badge/License-MIT-yellow.svg
[MIT]: https://opensource.org/licenses/MIT

***Rschema* provides a macro for generating JSON schemas from Rust structures.**

---

## Description

Often, you will use a framework such as **serde** to deserialize the contents of a configuration file into a Rust structure.

This tool generates schema information for the target file from the structure to be deserialized.

This supports pre-validation of the configuration file.

## Example code

```rust
use rschema::{
    Schema,
    Schematic,
};

// You can use serde's macros together.
use serde::Deserialize;

#[derive(Debug, Schematic, Deserialize)]
#[rschema(additional_properties)]
struct Custom {
    #[rschema(field(
        title = "A flag for debugging",
        description = "Set `true` to display debug logs.",
    ))]
    debug_flag: bool,
}

#[derive(Debug, Schematic, Deserialize)]
struct AppConfig {
    #[rschema(
        field(
            title = "Application Config",
            description = "Application configuration file.",
        ),
        required,
    )]
    app_name: String,

    #[rschema(
        field(
            title = "Version",
            description = "Application version.",
            pattern = r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$",
        ),
        required,
    )]
    version: String,

    #[rschema(field(
        title = "Custom Configuration",
        description = "Additional custom configuration.",
    ))]
    custom: Custom,
}

fn main() -> rschema::Result<()> {
    Schema::new::<Config>("Application Config")
        // Add description if needed.
        .description("Application configuration file.")
        // Save as file.
        .write_pretty("config.schema.json")?;
    
    Ok(())
}
```

The above code generates the following file:

```json
{
  "title": "Application Config",
  "description": "Application configuration file.",
  "type": "object",
  "properties": {
    "app_name": {
      "title": "Application Config",
      "description": "Application configuration file.",
      "type": "string"
    },
    "version": {
      "title": "Version",
      "description": "Application version.",
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
    },
    "custom": {
      "title": "Custom Configuration",
      "description": "Additional custom configuration.",
      "type": "object",
      "properties": {
        "debug_flag": {
          "title": "A flag for debugging",
          "description": "Set `true` to display debug logs.",
          "type": "boolean"
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "app_name",
    "version"
  ],
  "additionalProperties": false
}
```

It can be used with support tools such as VSCode.

## Combination with serde

*Rschema* and *Serde* can be used together.

Files that pass validation with the JSON schema generated by *Rschema* will be always successfully deserialized to the same data.

```rust
fn main() -> std::io::Result<()> {
    let config_json_str = std::fs::read("config.json")?;
    let config: Config = serde_json::from_str(&config_json_str).unwrap();

    // ...

    Ok(())
}
```