Name meta schemas something other than "draft-"

[handrews]

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]

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

[handrews]

@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]

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]

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

[gregsdennis]

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]

@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]

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

[awwright]

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]

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

[handrews]

@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]

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]

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

[gregsdennis]

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

[Relequestual]

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]

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]

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]

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

[MightyEagle82]

I want to put my 5 cents too because I use JSON schema in my job. :)

Reasons why a number as the version is preferable than a date are very simple:

1. number says "how many" and date says "when"
2. number is much easier to remember

So I think the current versioning sheme should be left.

Possibly one thing should be changed. It is "draft" word. Unless the specification is still a draft.

[handrews]

@ArtyomSafronov

• The specification is still a draft
• The numbers don't even really tell you "how many", it just sorta looks that way, more or less
• The pattern "draft-NN" has a specific meaning within the IETF and we are overloading it, which is a problem

[handrews]

OK, here's what I am probably going to do, using an assumed publication date of February 2019 as an example, and the vocabulary names from #697. @gregsdennis I renamed the output schemas (both your new ones and my old hyper-schema one) a bit here so please take a look at that.

I decided to preserve the long-standing "schema" and "hyper-schema" meta-schemas outside of the more complex directory structure. I left the equally long-standing "links" there as well but wonder if I should put it under a "defs" directory as a data structure definition? I don't think it's used much on its own.

https://json-schema.org/draft/
    2019-02/
        schema                      # Functionally identical to current "schema"
        hyper-schema                # Functionally identical to current "hyper-schema"
        links                       # Ditto for current "links", or should this move?
        meta/                       # These are single-vocab meta-schemas, NOT vocab URIs
            core
            applicator
            validation
            format
            content
            meta
            hyper-schema            # Could be confusing- "hyper-schema-only"?
        output/
            schema                  # Currently checked in as "output-schema"
            verbose                 # Currently "standardized-output-verbose"
            hyper-schema            # Existing hyper-schema-output, but updated
        vocab/                      # Vocab URIs, no documents (as requried by spec)
            core
            applicator
            validation
            format
            content
            meta
            hyper-schema            

I'm not sure what to do about the possible hyper-schema name confusion. Right now I figure that the shorter one is what people usually want, and other people can put in more effort and figure it out.

Regarding "meta" as a vocabulary name: yes, that does mean there will be a https://json-schema.org/draft/2019/02/meta/meta. Feel free to come up with a better name for that vocabulary, no one has suggested anything else in #697 so far.

@awwright @Relequestual @Julian @gregsdennis @philsturgeon @dlax @johandorland @jgonzalezdr @KayEss @ucarion

[gregsdennis]

I'm fine with this.

Are we doing anything to address the inconsistency with the other drafts? I'm worried about newcomers who wouldn't be aware of the history and this change.

[handrews]

@gregsdennis if you've got any ideas on the inconsistency let me know. We can't remove the existing meta-schemas, and even if we did that would not technically invalidate their URIs as identifiers.

Really, my plan is to just put a really big announcement on the front page of json-schema.org, and maybe add something to "Understanding JSON Schema" about it?

We will not be the first to convert from sequential to date-based numbering by a long shot. It is increasingly common for programming languages (although at year scope rather than month). I'm hoping that that helps a bit.

[gregsdennis]

I think a chronology on the sites will be fine. Just wanted to make sure it's covered.

[Relequestual]

I think this is fine.