Should we direct people to draft-4 for use in the wild?

[Relequestual]

I've had the concern for a while that draft 3 and 4 are in use, and now draft 5 is published, there's a greta chance of confusion for the general userbase.

Raised at #50 (comment)

I understand that Internet Drafts are DRAFTS and not really intended to be used, however the reality is that draft 3 and 4 re being used. Some libraries even suggest they spport a number of draft 5 features! (http://epoberezkin.github.io/ajv/keywords.html).

I wonder if the website and readme for the repo, should direct people to draft 4 in terms of what should be used for now, till the I-D becomes a proper standard?

I guess I'm mainly asking the community what they think on this one. I don't know what has happened in the past with other I-Ds that have been used before evolving out of the draft status.

[awwright]

I think when the IETF says these are drafts, and shouldn't be cited, it means other standards shouldn't rely on any of the behavior. In some cases, drafts will use different keywords, or prefixed keywords.

X- used to be popular until it was deprecated, because it was getting written into finished standards.

RFCs require two interoperable implementations for publication. So drafts are used for implementing functionality. HTTP/2 implementations used a special protocol keyword for implementations against the draft, so as to be incompatible with the final version ("h2" was the keyword chosen).

On the whole, as far as my opinion goes, I would consider the JSON Schema project to be the meeting place where JSON Schema library authors work to converge on a common behavior and common semantics. We use the website to document the vocabulary for people writing schemas, and we publish I-Ds and eventually an RFC for writing implementations against.

So I suppose my suggestion is, let's work on the website, and publish more stuff there (for authors/general audiences), and keep publishing drafts (for implementors).

[Relequestual]

Standards are hard...
Having just read http://seriot.ch/parsing_json.html, I'm not sure of I'm more or less worried about the world in general.

I think I can understand your perspective on this issue, being more flexible. As I've mentioned before, I tend to be want to tighten things down rather than be flexible in terms of collaborative projects, but I guess I need to learn that isn't always the approach most helpful to keep a thing moving forward.

[handrews]

Having just read http://seriot.ch/parsing_json.html, I'm not sure of I'm more or less worried about the world in general.

If anything this is a reason to pay a bit more attention to CBOR (see #6 ).

@awwright I agree with everything you've written but don't see the answer to the question: when we're doing the "let's work on the website, and publish more stuff there (for schema authors/general audiences)" part, should the "stuff" in question focus on Draft 04 or on whatever our current I-D is? Or should we address both but keep things somewhat separate, making it clear that Draft 04 became a de-facto standard while the project was dormant, while the further I-Ds are expected to change more rapidly?

[Relequestual]

...making it clear that Draft 04 became a de-facto standard while the project was dormant, while the further I-Ds are expected to change more rapidly?

That's what I wanted to convey. Thanks.

[awwright]

@Relequestual To summarize, or clarify, I think implementations should be using the latest published draft -- this is sort of the whole point of the I-D.

For others, let's document the best practices on the website. We can lay out things for the layperson far easier and prettier with the website.

[Relequestual]

OK. I think I would be happier if the home page of the site included the latest version number (with date) and a link to a previous releases list. Happy to open a new issue for this.

[awwright]

Yeah, I keep forgetting to get around to updating the website.

[Relequestual]

For ease when I'm creating a new issue on the site repo, what's the url for draft 5 please? =]

[awwright]

What do you mean, like https://tools.ietf.org/html/draft-wright-json-schema-00?

[Relequestual]

Yup. Thanks. Brain fail that day

[awwright]

Any new comments on this?

I think the goal to work towards looks like:

1. we use the website to document how to write a schema, and schema authoring best practices
2. the I-D defines what implementations must do, and
3. we specify that implementations can also use their best judgement to implement reverse compatibility for existing schemas, and provide a test suite to assist in this

[Relequestual]

Sorry for the delay in looking at this issue again... Had many issues before it in the stack...

I think we fixed some of the issues I raised within this issue.

What I really mean by this issue is, should we direct users of JSON Schema to using draft-4, as a more stable version of JSON Schema? I think you feel we shouldn't do that, but we are not developing new drafts in a more rapid progression...

This is more a discussion issue... which I generally disslike, but here we are.
/nudges @handrews

[handrews]

I feel like we're reasonably close to releasing draft 6, which will hopefully be a pretty solid draft with a functioning meta-schema release alongside it. If we stick with our current review process and, from draft 6 on, always keep the meta-schema in sync with the spec and deployed simultaneously, then we should not have any problems with folks picking the most current draft.

I think the question of what schema authors will use "in the wild" will be determined based on who implements support for which draft, and I think that's fine.

For schema validator/hyperclient implementors, really the only reason to tell them not to implement a particular draft is if we think there are too many bugs in it and they should wait for the next one. We can put notices like that on the web site if we want.

I would really prefer to encourage people to not stay on draft 4. We only get feedback on new drafts if people use them, so I would rather be more rigorous about ensuring that each draft is usable and that its use can be declared via meta-schema choice. And then encouraging implementations to support each one. That is how we will learn whether our changes are in the right direction or not.

I am working on a draft 6 compliant implementation and I believe @epoberezkin intends to support draft 6 in Ajv as soon as the draft is finalized. Getting new drafts in front of schema authors is the best thing we can do to advance the project, I think.

[epoberezkin]

@handrews yes, working on it.

We need to add tests to JSON-Schema-Test-Suite too, it should also be done together with the release (or soon after). I was going to submit some tests there. Given that draft-6 is backward compatible I would rather only add additional tests there and add a note that draft-4 tests should pass too. And even if we want to drop some tests, we could add some extra property to the test to indicate it's draft 4 only. I think it is better that duplicating all the tests in the new folder... Do you agree?

[handrews]

@epoberezkin let's take the test structure discussion to json-schema-org/JSON-Schema-Test-Suite#136 rather than cluttering this issue. I haven't looked at the test repo enough to have an opinion on your question yet anyway :-)

[smyrman]

OK. I think I would be happier if the home page of the site included the latest version number (with date) and a link to a previous releases list. Happy to open a new issue for this.

Would be really sweet to have docs for v4 still available on json-schema.org. E.g. for linking to in issues for libraries still implementing only draft4 support. I can find the old JSON Schema core specs on https://tools.ietf.org/html/, but not the validation spec...

UPDATE: I now found the link in the changelog to draft-fge-json-schema-validation-01. However, this link appears to be dead. Should it have been draft-fge-json-schema-validation-00?

[awwright]

@smyrman draft-04 is still the latest meta-schema, the latest Internet-Drafts update and revise some of the language and updates to how to write schema documents, but there shouldn't be many significant changes for implementations.

Where's the source of the link? The latest document for JSON Schema Validation is draft-wright-json-schema-validation-00

[Relequestual]

@smyrman If I understand, you were looking for links to the old draft documents. I agree this would be useful. We have created this list on this repos wiki page: https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links

I think we should add a link to said page on the docs section of the website.

[Relequestual]

There has been discussion over the past month that we, the maintainers of JSON Schema, agree that we will not release a draft-5 meta schema, and that generally we will encouridge people to use draft-4. ALSO, when draft-6 is published, this will not be so much of an issue. As such I'm closing this issue.