New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Name meta schemas something other than "draft-" #612

Open
handrews opened this Issue Jun 18, 2018 · 18 comments

Comments

@handrews
Member

handrews commented Jun 18, 2018

We often get complaints about how confusing the draft numbering is, not just from people new to JSON Schema, but from people such as members of the IETF JSON working group.

We kept the sequential draft numbering for meta-schemas mostly because of inertia, and because that's how many of us (and others) would talk about future work even while things were stalled on draft-04 (the last meta-schema where the number appeared in at least one of the IETF draft names).

I propose dropping this for "draft-08" and calling the meta-schemas something else, ideally along with a shift to HTTPS. Since we will have a larger set of modular vocabulary meta-schemas (in addition to the core+applicators+validation+basic-annotation, and all of that +hyper-schema meta schemas that we have now, which will be retained for convenience), it feels like a good opportunity to reconsider how we identify these.

One option might be to take a cue from modern JavaScript and use years, or years+month as we at least sometimes publish two updates a year. Assuming a September publication of the next set:

meta would be for the convenience meta-schemas, which are all that most people would use:

https://json-schema.org/09-2018/meta/schema
https://json-schema.org/09-2018/meta/hyper-schema

vocab would be for per-vocabulary meta-schemas, which are mostly building blocks for the convenience meta-schemas (see #561)

https://json-schema.org/09-2018/vocab/core
https://json-schema.org/09-2018/vocab/applicators
https://json-schema.org/09-2018/vocab/validation
https://json-schema.org/09-2018/vocab/basic-annotation
https://json-schema.org/09-2018/vocab/hyper-schema

I don't like the name basic-annotation but that's not the point, please don't fixate on the exact list of vocabularies or their name, we will sort that out as the vocab PRs get written.

I'm not entirely sure what to do with the LDO schema. It's not really a meta-schema, as LDOs on their own are not schemas. Although they contain schemas. Possibly still meta? Or maybe something else like components? If we go forward with a hypermedia operations object, there would likely be another schema of this sort.

https://json-schema.org/09-2018/components/links

Thoughts?

@gregsdennis

This comment has been minimized.

Show comment
Hide comment
@gregsdennis

gregsdennis Jun 18, 2018

Collaborator

For clarity, what is the objection to the draft-* naming scheme? I find it quite simple.

Collaborator

gregsdennis commented Jun 18, 2018

For clarity, what is the objection to the draft-* naming scheme? I find it quite simple.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Jun 18, 2018

Member

@gregsdennis you're apparently the only one! The IETF drafts reset their numbers each time a new editor does the publishing, or each time a new draft is split off (as there's no notion of a suite of specifications, even though there are quite a few such suites, e.g. RFCs 7230-7240 for the revision of HTTP/1.1)

I've repeatedly had people complain that they couldn't figure out what draft to look at (no, I don't understand that either, I think the web site is quite clear). And a lot of people can't seem to figure out the correspondence (even though the specifications name their meta-schema explicitly). I say "a lot", I mean "enough that it's a notable and rather frequent recurring irritation".

But perhaps most importantly, the IETF working group people seemed kind of upset about it. I mean, some of them were also upset that we had a keyword called minimum because they personally saw no use for it, so... ¯\(ツ)/¯ But it was viewed as misleading since there's no actual draft-*-json-schema-07 anywhere.

Member

handrews commented Jun 18, 2018

@gregsdennis you're apparently the only one! The IETF drafts reset their numbers each time a new editor does the publishing, or each time a new draft is split off (as there's no notion of a suite of specifications, even though there are quite a few such suites, e.g. RFCs 7230-7240 for the revision of HTTP/1.1)

I've repeatedly had people complain that they couldn't figure out what draft to look at (no, I don't understand that either, I think the web site is quite clear). And a lot of people can't seem to figure out the correspondence (even though the specifications name their meta-schema explicitly). I say "a lot", I mean "enough that it's a notable and rather frequent recurring irritation".

But perhaps most importantly, the IETF working group people seemed kind of upset about it. I mean, some of them were also upset that we had a keyword called minimum because they personally saw no use for it, so... ¯\(ツ)/¯ But it was viewed as misleading since there's no actual draft-*-json-schema-07 anywhere.

@gregsdennis

This comment has been minimized.

Show comment
Hide comment
@gregsdennis

gregsdennis Jun 19, 2018

Collaborator

In regard to IETF, if we're trying to publish within their domain, then adopting their versioning scheme makes sense. Even so, if this were software, I'd use 0.x.y[beta z] versioning, but given that this is an unofficial/still-under-development specification, draft-* makes sense for now.

Collaborator

gregsdennis commented Jun 19, 2018

In regard to IETF, if we're trying to publish within their domain, then adopting their versioning scheme makes sense. Even so, if this were software, I'd use 0.x.y[beta z] versioning, but given that this is an unofficial/still-under-development specification, draft-* makes sense for now.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Jun 19, 2018

Member

@gregsdennis I'm not sure what you mean here. My point is that our usage of "draft-" violates IETF norms.

Member

handrews commented Jun 19, 2018

@gregsdennis I'm not sure what you mean here. My point is that our usage of "draft-" violates IETF norms.

@gregsdennis

This comment has been minimized.

Show comment
Hide comment
@gregsdennis

gregsdennis Jun 19, 2018

Collaborator

Yes. Use what they have to join their cult. 😉


I think draft-* makes sense for development, just like a beta version does for software. But if they're complaining about it, and their scheme makes sense, then I don't see a problem with changing.

Collaborator

gregsdennis commented Jun 19, 2018

Yes. Use what they have to join their cult. 😉


I think draft-* makes sense for development, just like a beta version does for software. But if they're complaining about it, and their scheme makes sense, then I don't see a problem with changing.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Jun 19, 2018

Member

@gregsdennis their scheme makes sense for drafts. It does not make sense for end users, who really should not have to figure out the correct order of draft-wright-json-schema-validation-01 vs draft-handrews-json-schema-validation-00, not to mention that the meta-schemas and documents do not change in lockstep. Which is why I am proposing something entirely different.

Member

handrews commented Jun 19, 2018

@gregsdennis their scheme makes sense for drafts. It does not make sense for end users, who really should not have to figure out the correct order of draft-wright-json-schema-validation-01 vs draft-handrews-json-schema-validation-00, not to mention that the meta-schemas and documents do not change in lockstep. Which is why I am proposing something entirely different.

@dlax

This comment has been minimized.

Show comment
Hide comment
@dlax

dlax Jun 19, 2018

Member

Using date-based version looks good to me. But perhaps YEAR-MONTH is better so that versions would be correctly sorted.

Member

dlax commented Jun 19, 2018

Using date-based version looks good to me. But perhaps YEAR-MONTH is better so that versions would be correctly sorted.

@awwright

This comment has been minimized.

Show comment
Hide comment
@awwright

awwright Jun 20, 2018

Member

This doesn't seem any worse to me, except possibly it's more difficult to remember.

The W3C used dates for a while to prefix everything, even the most important URI in RDF, http://www.w3.org/1999/02/22-rdf-syntax-ns# which absolutely nobody can remember.

I don't think that's as much of a concern here, though.

Member

awwright commented Jun 20, 2018

This doesn't seem any worse to me, except possibly it's more difficult to remember.

The W3C used dates for a while to prefix everything, even the most important URI in RDF, http://www.w3.org/1999/02/22-rdf-syntax-ns# which absolutely nobody can remember.

I don't think that's as much of a concern here, though.

@Anthropic

This comment has been minimized.

Show comment
Hide comment
@Anthropic

Anthropic Jul 2, 2018

Collaborator

ISO date format yyyy-mm-dd is easier for sorting folders too.

Collaborator

Anthropic commented Jul 2, 2018

ISO date format yyyy-mm-dd is easier for sorting folders too.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 9, 2018

Member

@dlax @Anthropic I'm on board with year-first, not sure why I did not write it that way to start with, goodness knows I've dealt with sorting date strings before...

@awwright that's definitely a relevant point about memorability, but agree that it's probably manageable here. When we get to a true ratified standard version, I would prefer not to identify it by a date, or at most use the two- or four-digit year (like some programming languages do- C99, C11, C++11, C++14, ES2016, ES2017, etc.)

We've mostly managed to produce two rounds of drafts a year, although I think this year only one that changes the meta-schema. So we should include the month for drafts, I think.

Member

handrews commented Sep 9, 2018

@dlax @Anthropic I'm on board with year-first, not sure why I did not write it that way to start with, goodness knows I've dealt with sorting date strings before...

@awwright that's definitely a relevant point about memorability, but agree that it's probably manageable here. When we get to a true ratified standard version, I would prefer not to identify it by a date, or at most use the two- or four-digit year (like some programming languages do- C99, C11, C++11, C++14, ES2016, ES2017, etc.)

We've mostly managed to produce two rounds of drafts a year, although I think this year only one that changes the meta-schema. So we should include the month for drafts, I think.

@Relequestual

This comment has been minimized.

Show comment
Hide comment
@Relequestual

Relequestual Sep 19, 2018

Member

I find this strange, but it's clearly an issue.

I guess it's confusing because people expect to match "draft-n" to an IETF URL, as described above, which also makes it strange and unusual for IETF folk and non spec people alike.

We will have to provide a mapping or a list per release, right?

I can see and understand why it's confusing, but I also feel we shouldn't have to change it.
That being said, I'm not raising an objection to the change.

YYYY-MM should be OK, yeah.

At least it shows the project is ALIVE! =]

Member

Relequestual commented Sep 19, 2018

I find this strange, but it's clearly an issue.

I guess it's confusing because people expect to match "draft-n" to an IETF URL, as described above, which also makes it strange and unusual for IETF folk and non spec people alike.

We will have to provide a mapping or a list per release, right?

I can see and understand why it's confusing, but I also feel we shouldn't have to change it.
That being said, I'm not raising an objection to the change.

YYYY-MM should be OK, yeah.

At least it shows the project is ALIVE! =]

@awwright

This comment has been minimized.

Show comment
Hide comment
@awwright

awwright Sep 19, 2018

Member

That's actually a pretty good rationale to not call it draft-nn, I think.

Member

awwright commented Sep 19, 2018

That's actually a pretty good rationale to not call it draft-nn, I think.

@gregsdennis

This comment has been minimized.

Show comment
Hide comment
@gregsdennis

gregsdennis Sep 19, 2018

Collaborator

Will we retroactively rename the existing drafts based on release date?

Collaborator

gregsdennis commented Sep 19, 2018

Will we retroactively rename the existing drafts based on release date?

@Relequestual

This comment has been minimized.

Show comment
Hide comment
@Relequestual

Relequestual Sep 19, 2018

Member

Oh, I thought this was only for naming the meta schema, not changing the name of the actual draft "version" too.

I don't think we SHOULD rename old drafts retroactively. There's a lot of content and documentation out there about how to do stuff in draft-4 or 7 or whatever. Renaming those to dates will make finding off site help pretty hard to google for!

Member

Relequestual commented Sep 19, 2018

Oh, I thought this was only for naming the meta schema, not changing the name of the actual draft "version" too.

I don't think we SHOULD rename old drafts retroactively. There's a lot of content and documentation out there about how to do stuff in draft-4 or 7 or whatever. Renaming those to dates will make finding off site help pretty hard to google for!

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 19, 2018

Member

Only for meta-schemas, definitely will not rename existing. Could potentially alias the to date-names, though. Yanking them from their current URIs would be bad. It's one thing to replace a meta-schema when it actually fails to validate correct schemas (which has been the case several times in the past). It's another thing entirely to remove a well-known URI.

Member

handrews commented Sep 19, 2018

Only for meta-schemas, definitely will not rename existing. Could potentially alias the to date-names, though. Yanking them from their current URIs would be bad. It's one thing to replace a meta-schema when it actually fails to validate correct schemas (which has been the case several times in the past). It's another thing entirely to remove a well-known URI.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 19, 2018

Member

I guess it's confusing because people expect to match "draft-n" to an IETF URL, as described above, which also makes it strange and unusual for IETF folk and non spec people alike.

Yes, it comes up a lot, and was one of the reasons for some IETF JSON mailing list folks to ignore us. They were just like "there is no draft-07" and wouldn't even look at it.

We will have to provide a mapping or a list per release, right?

We already have to do this. I have to explain this all the time when I try to promote JSON Schema. I have to re-explain it fairly often in the context of OpenAPI, particularly as they are using the draft that doesn't map directly to a meta-schema anyway ("draft-05")

Member

handrews commented Sep 19, 2018

I guess it's confusing because people expect to match "draft-n" to an IETF URL, as described above, which also makes it strange and unusual for IETF folk and non spec people alike.

Yes, it comes up a lot, and was one of the reasons for some IETF JSON mailing list folks to ignore us. They were just like "there is no draft-07" and wouldn't even look at it.

We will have to provide a mapping or a list per release, right?

We already have to do this. I have to explain this all the time when I try to promote JSON Schema. I have to re-explain it fairly often in the context of OpenAPI, particularly as they are using the draft that doesn't map directly to a meta-schema anyway ("draft-05")

@Relequestual

This comment has been minimized.

Show comment
Hide comment
@Relequestual

Relequestual Sep 19, 2018

Member

They were just like "there is no draft-07" and wouldn't even look at it.

This makes me so sad.

We already have to [provide a mapping].

Yeah, I think my point was lost, in that we would just have to update it.

Member

Relequestual commented Sep 19, 2018

They were just like "there is no draft-07" and wouldn't even look at it.

This makes me so sad.

We already have to [provide a mapping].

Yeah, I think my point was lost, in that we would just have to update it.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 19, 2018

Member

This makes me so sad.

That entire thread still makes me so sad.

Yeah, I think my point was lost, in that we would just have to update it.

Oh right, definitely.

Member

handrews commented Sep 19, 2018

This makes me so sad.

That entire thread still makes me so sad.

Yeah, I think my point was lost, in that we would just have to update it.

Oh right, definitely.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment