Draft 6 publication checklist

[handrews]

This tracks all of the stuff around getting Draft 6 out the door other than actually submitting it to the IETF as a new personal draft. It's mostly to help me remember what to review during the final review period. Plus some stuff that's really obvious but felt like it should be on the list :-) I don't expect anyone else to take action on this issue, but please comment if you know of something that does not make sense as an issue/PR against the spec that should get tracked.

• Test cases for Draft 6 (and Draft 5 as needed)
• Final review: Verify that the meta-schema and specification match
• Final review: Overall spelling, grammar, and wording consistency check
• Final review: Verify that all examples make sense and match current specs
• Final review: Verify that all notable changes are in the changelog section
• Submit drafts to IETF
• Update the web site
• Announce to mailing list

[awwright]

@handrews The process I'll follow is listed on the wiki page, take a look at that and let me know if you think that's missing anything from here.

[handrews]

@awwright the main point here is the final review stuff. That is not in your process, and wikis don't track anything anyway. You don't need to do anything for this issue, so if you don't find it useful please just ignore it.

[Relequestual]

I agree with this list of requirements before rubber stamping the draft.

[Relequestual]

@handrews Can any of these checks be checked? =]

[Relequestual]

@epoberezkin How are the updates to the tests coming along?

[epoberezkin]

@Relequestual They are coming ok, not too much left to do: json-schema-org/JSON-Schema-Test-Suite#153

[handrews]

@epoberezkin can you verify that the schema.json and hyper-schema.json currently on master validate themselves? And the hyper-schema.json validates links.json? If so we can copy them over to the web site repo and update the URIs in preparation for release.

[epoberezkin]

@handrews there are the following problems:

• schema.json (meta-schema)
  • $id should be version specific, we have agreed not to use unversioned URIs I think
• hyperschema
  • $id should be version specific
  • unless I am missing something, inside /definitions/schemaArray should be anyOf and each subschema inside anyOf should be similar to schemaArray definition in meta-schema
  • $ref to schema inside /definitions/schemaArray is wrong: it is unversioned and it is different from the current $id in schema (URI segment "drafts" in $ref vs "draft" in $id).

That's the failing code, once these issues are fixed we can try again: https://runkit.com/esp/58b87f8dc8e4bd0015b7a0f6

[handrews]

@epoberezkin I think have addressed these, although the way I solved the schemaArray is slightly different (trying to minimize how much gets redefined).

[epoberezkin]

@handrews You mean in the PR? Ah... You've asked me to check the files in master branch.

[handrews]

@epoberezkin I originally asked you to check the master, but just now I made a new PR which you should check. I'll update that PR until it passes your checks.

[epoberezkin]

@handrews sure, on it.

[epoberezkin]

I am looking at https://github.com/handrews/json-schema-spec/tree/metaversion

[handrews]

@epoberezkin thanks- yes, that's correct.

I tried to do it myself in that web interface but hit errors that I couldn't figure out, and wasn't sure if I'd messed up the JS, the usage of Ajv, or something else :-P My JavaScript skills are outdated by a lot.

[epoberezkin]

@handrews it all works, all three schemas are valid according to themselves / their meta-schemas: https://runkit.com/esp/58b87f8dc8e4bd0015b7a0f6

[handrews]

Examples verified and bugs fixed in PR #269

[epoberezkin]

@awwright @handrews @Relequestual is there any expected time for publication of draft-06? What is left to do?

[handrews]

I'm hoping to hear one more response from @jdesrosiers on #280, and then (if he and I don't converge on one or the other), @awwright needs to make a call between #280 and #284, or submit his own clarification. Given that the two people who have attempted to create demo hyper-schemas so far can't agree on how they work, some clarification is absolutely critical before publishing the draft.

Additionally, #281, #282 are non-controversial (so far) and also awaiting @awwright's approval.

I am not aware of any other outstanding issues. We've had plenty of time now for the final review, and the hyper-schema confusion is the only thing that's come up.

[handrews]

I believe the milestone is accurate:
https://github.com/json-schema-org/json-schema-spec/milestone/2

[dlax]

While reviewing some PR recently, I noticed that many parts of the text of XML documents were still not wrapped. This makes reviewing more difficult IMHO as it requires horizontal scrolling github UI. Also, quite often, lines that get changed are wrapped along the way by commit authors (noticeably @handrews recently) so it seems to me that we're progressively wrapping everything.
Would it be a good time to do a "batch wrap" to 80-characters in every XML documents now (or after draft 6 release)? I can handle this if it helps.

[handrews]

@dlax if you want to post the PR go ahead, but I'd like to leave @awwright the option of tagging and publishing the draft immediately as the previous draft expires on Sunday. I don't want to delay publication for something that won't be visible to most readers.

Whether we take the formatting change just before or just after publishing this draft, I'd be a fan of doing that.

[handrews]

PUBLISHED!!!! WOO HOO!!!!

[nickcmaynard]

@handrews There's a few things left on the checklist - the website isn't yet updated, for example - did you mean to close this??

[handrews]

@nickcmaynard well, yes I meant to close it, but no I didn't realize things were missing. You're right of course.

[handrews]

@awwright do you want to make an announcement to the mailing list? If I don't hear from you or see an announcement in a few days, I'll go ahead and make one I guess. We should do that after updating the web site anyway, and I need to clear out all the big markdown changes first I think.

[awwright]

@handrews Just made a mailing list post

[erosb]

@handrews will there be any changelog for implementors?

[handrews]

@erosb there is a changelist at the end of each spec. Let me know if that's not sufficient, but it should indicate which keywords were added or changed. We can start a wiki page for clarifications as needed.

[handrews]

There is a document for hyper-schema because those changes were so extensive, but validation and core were relatively straightforward. Still, it's hard for me to tell what it's like to read the new specs fresh compared to working with them constantly so if you find stumbling blocks we can add more info.

[erosb]

Very nice @handrews , thank you. It doesn't seem to be such a big changelog as I thought, so I think I will support it in everit-org/json-schema in 3 months (although I have some other concerns there too).

[erosb]

2 more things came into my mind:

• somewhere it should be noted that https://tools.ietf.org/html/draft-wright-json-schema-01 is actually the draft-6 version
• also, is draft-6 backward-compatible with draft-4 ?

[handrews]

I'll update the web site today with the new draft/meta-schema numbers.

Validation and core are not backwards compatible: off the top of my head the change from "id" to "$id" and the changes in type/behavior for "exclusiveMaximum" and "exclusiveMinimum" are not compatible. And as noted, hyper-schema is very different. From the immediate previous draft, the newly added "uriref" format was is changed to "uri-reference" for consistency (given the lack of a draft-05 meta-schema, it wasn't widely implemented anyway).

[handrews]

Ok, now it's done!

(let's file new issues for any additions explanatory documentation)

[erosb]

Thank you guys for your hard work on it! 👍

[dlax]

Might be worth adding a draft-wright-json-schema-01 tag also.

[awwright]

@dlax Good catch, it looks like I didn't push the tags out somehow, I'll do that once I'm back at my desktop machine

[Relequestual]

Yeah you have to explicitly push tags with git cli. It's easy to do via the Github UI though =]