search

GREsau / schemars

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

Clarification external library support policy #131

Open nfwvogt opened 2 years ago

nfwvogt commented 2 years ago

First of thank you for this great project!

I wanted to ask for a clarification on the policy of including optional external libraries in json_schema_impls. In the recent pull requests #130 and #125 a preference for adding support in the original packages was mentioned. Are there certain criteria for including explicit impls for external libraries in json_schema_impls, e.g. how often it is used according to crates.io?

We would like to add support for complex numbers (num-complex) and n-dimensional arrays (ndarray) in some form upstream. Of those libraries especially num-complex is quite widely used and it might be difficult to add upstream schemars support to only part of num-traits. Would there be interest in a pull request for one or both of the implementations we have for both (num-complex, ndarray)?

ralpha commented 2 years ago

Good question!

TL;DR Depends on the crate and how niche it is. And the willingness for the external crate to add it themself, and maintenance of both this library and the other crate. But I have a strong preference for the implementation to be added to the external crate.

A bit longer answer is:

Background/disclaimer Schemars is maintained by GREsau (original author), but he has not been very actively maintaining it. I use Okapi in some of my projects which is also created by him (it uses Schemars as dependence). A bit less then a year ago I contacted him to increase the maintenance on that, and since then I have been the maintainer of Okapi.

Because Schemars is both a dependency there and to keep this project active I have also been keeping track of new issues here. But I don't have any special permissions in this repo (can not merge or commit to it). But most issues that come up are questions. So that has not been a big deal. (also did not reply to every issue as I only have limited time)

That to say I'm by no means an authority related to this project.

My view on the policy

Are there certain criteria for including explicit impls for external libraries in json_schema_impls, e.g. how often it is used according to crates.io?

GREsau his current policy seems to be this:

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 [...]

Source: #112

This is also the policy I have been reflecting in the issues/PR you mentioned. I have already been saying this because GREsau has not been working actively toward v1.0 so this might still be more than a year away. And making people wait for that is not what we want ether. And I can not merge PR's (although I can contact GREsau and try to get it merged that way).

I think that the json_schema_impls was a good way to make the crate usable for a large group of people. But I think you can agree that this is not a long term solution. This increases the maintenance cost of this create a lot and as we see it is not every actively maintained at this point in time.

So I think we should just force external create to start implementing it for there own type. If and when breaking changes will happen we can deal with it then. If you disagree with me that is fine, but then we need some more maintainers for this crate and we currently don't have any/many.

Conclusion We need a proper public policy on this, I know. But we also need (more) maintainers.

We would like to add support for complex numbers (num-complex) and n-dimensional arrays (ndarray) in some form upstream. Of those libraries especially num-complex is quite widely used and it might be difficult to add upstream schemars support to only part of num-traits. Would there be interest in a pull request for one or both of the implementations we have for both (num-complex, ndarray)?

With all things above said it is hard to say. It would be nice if the external libs could implement it, but I know nom is big so I would not exclude it being added here. (but I can not merge, only offer feedback so GREsau does not have to spend a lot of time reviewing the PR)

nfwvogt commented 2 years ago

Thank you very much for the thorough feedback! I'll ask in the corresponding libraries if there is interest in a pull request for schemars support. If there is a negative response, I will probably open a pull request here with the corresponding information so that GREsau can have a look and decide when/if he has time.

kyrias commented 1 year ago

This just came up for us due to there being implementations for chrono, but not for chrono_tz::Tz.