search

GREsau / schemars

Generate JSON Schema documents from Rust code
https://graham.cool/schemars/
MIT License
826 stars 229 forks source link

Project Status and Road to 1.0 #112

Open GREsau opened 3 years ago

GREsau commented 3 years ago

I've been working on Schemars for a little over 2 years now - it's always just been a personal project of mine, which does mean its progress depends on my free time and motivation. But I am certainly still here, and plan to continue working on it!

With that in mind, I thought it was worth recording some thoughts about where I see the project going, and specifically what I think is necessary to reach something I can could version 1.0.

I'd love to reach a point where Rust library authors can implement JsonSchema on their public types (probably depending on feature flags), much like is commonly done for serde::Serialize/Deserialize. But I'm not comfortable encouraging this too much yet, as I don't think the Schemars API is quite yet stable enough - there are still some enhancements and changes that I would love to see implemented which may require breaking changes to the current API. So, to be comfortable in releasing Schemars v1.0, I'd like to be reasonably confident that all desired enhancements can be implemented without breaking changes. Ideally, there would never need to be a v2.0. Off the top of my head, I would like to have solutions for:

Note that these do not necessarily have to be implemented for 1.0, I just need to know that they could be done without breaking changes. There are a few ways to achieve this - it could be a proof-of-concept implementation, or just an API proposal with a vague idea of how that API could be implemented.

⚠️ Bear in mind that until Schemars reaches 1.0, breaking changes are likely! Though of course, I prefer to avoid them where reasonably possible. Any breaking changes will continue to be documented in the changelog, and never released in a semver patch version change.

There are some more "indirect" improvements I'd like to get done, like writing up some contributor guidelines to make it easier for people to create useful PRs. I'm also interested in looking into the performance of Schemars, in particular the compile-time performance, including #[derive(JsonSchema)]. I assume that the actual schema generation at runtime is rarely in a hot path, so runtime performance is less of a concern (but not unimportant!), I would be very interested to hear if you don't agree.

And finally, I'd like to take this opportunity to thank the community contributors - all of the bug reports, enhancement suggestions, and code contributions have been a massive help, so thank you all! ❤️

ModProg commented 1 year ago

I noticed that progress e.g. on the reviewing of PR's seams to have stagnated. I don't want to complain about that, because this is obviously a project you are developing in your free time, but I wanted to offer my help with those tasks, as

I use schemars in my projects and would prefer contributing to the original crate instead of forking it to implement the necessary features.

jayvdb commented 1 year ago

Note there has been an update worth reading at https://github.com/GREsau/schemars/issues/225#issuecomment-1685352926 for anyone wanting to knowing the current status and plans.

GREsau commented 1 year ago

Please see https://github.com/GREsau/schemars/issues/242 for a proposal on how schemars's Schema type may be redefined in a way that's flexible enough to support multiple versions/dialects of JSON Schema. It's certainly not as formal as a Rust RFC, but I wanted to put something out for feedback before investing substantial time into implementing it 🙂

juntyr commented 2 months ago

I'm very excited to see your push for v1.0 and have been testing the alpha versions in my project.

Do you have a rough order-of-magnitude estimate for when v1.0 might be released, e.g. days, weeks, months? I'm trying to decide whether I should pin a specific alpha version in my crate in its soon-ish crates.io release or just wait for v1.0 before releasing mine - either way I'm fine, so please don't take the interest as additional pressure :)

GREsau commented 2 months ago

Do you have a rough order-of-magnitude estimate for when v1.0 might be released, e.g. days, weeks, months?

Definitely not days, possibly weeks, but realistically much more likely months.

I was hoping that the "stable" version of JSON Schema would be ready soon so that schemars could use it as the default version, but I'm not aware of an ETA for that, so we may need to live with draft 2020-12 being schemars's primary version forever. That doesn't mean schemars won't be able to support newer versions, of course, so it's probably fine.

GREsau commented 2 months ago

I've been doing some thinking about how to support "generation of separate schemas for serialization/deserialization", and written up some notes in comments starting from https://github.com/GREsau/schemars/issues/48#issuecomment-2295283276 - feedback on them would be very welcome!