FEEDBACK WANTED - API proposal - supporting multiple JSON schema versions, breaking changes to `Schema` definition about schemars

[ahl]

I like this idea of (roughly) JsonSchema::json_schema(..) -> serde_json::Value a lot. At first, I thought it was weird and lame, but the more I thought it over, the more it appeals to me. Consider my own use case: we're using schemars for a bunch of OpenAPI related stuff. We have to specify that we're interested in the OpenAPI format and fish around the extensions for nullable. It would be much crisper to just get back a json Value and use that as is.

Your insight that this divorces the output type from the weird differences of various JSON schema revisions is extremely compelling. This even opens the door for a generic "schema" representation that can have a JsonSchema impl (e.g. https://crates.io/crates/schema and there could be a impl<T:schema::Schema> schemars::JsonSchema for T {}).

One could imagine schema descriptions even unrelated to JSON schema... though perhaps that's a bridge too far.

In addition, I think it makes a ton of sense to have the structural use of JSON schema types live in a different crate -- the design goals are distinct and not necessarily well-aligned.

One question: do you definitely want to use serde_json::Value? On one hand, consumers of schemars almost certainly also depend on serde_json. On the other hand, I've often wished there were a distinct Value object so I didn't need to pull in all of serde_json.

---

This does seem to complicate hand-written JsonSchema implementations in that one might need to pay closer attention to the generation settings. It might be useful to provide some mechanism that's effectively "here's my output in 2019-09" format, could you please transform this according to what the caller is asking for?"

---

Cool stuff; would be happy to contribute; I've already been planning a 2020-12 JSON Schema crate for an OpenAPI v3.1 compatible version of https://crates.io/crates/openapiv3

[gagbo]

Hello,

The changes all make sense, as my main (only) use case for the library is to produce programmatically the #/components/schemas part of an OpenAPI schema from a collection of Rust structs, I’m very happy to see it’s going to provide some extra flexibility in usage.

For the ability to produce extra schema outputs, I feel like that having the option to specify in the json_schema call which variant to target is going to be the simplest thing to do. For all people that don’t know/care about the version, we could have both json_schema and json_schema_with_spec or something.

I’d like the ability to also output the data to yaml format if possible, it would be useful at least for my use case I think. But the more I think about it, the more I think that I might just want a macro that creates an openapiv3::Schema from arbitrary structs, so maybe all of this is irrelevant and I should just look into the code that respects serde attributes here.

I think all the specific getters/setters like format() set_format would fit better if they were added to extension traits like trait JsonSchema202012 which you’d implement on Schema. This way consumers that want to use these would need to bring the trait in scope and it would make completion/method list smaller. Also it would allow external crates to implement their own extension traits if they want to, I think.