Clarify the specification links are to the latest version of the schema

[seagreen]

Currently it's implied the links are to Draft 4, but they're not.

[Relequestual]

Right! It should say draft 5. I'll fix!

Edit:

Actually, I'm not sure. The latest is draft 5, but iirc there's no metaschema, so the section after that would then become invalid.

@awwright @handrews Suggestions

[awwright]

Perhaps we should just remove the version identifier and use a date, for the documents.

And with this method, v4, and later v5, can identify the meta-schemas.

[handrews]

@awwright that seems like a good idea. Also, I feel like we should give ourselves the option of releasing updates to the three different documents independently, and the v4, v5... notation doesn't hold up well to that. But if we have some nice core and validation fixes to get feedback on while we're bogged down on some big hyper-schema thing, it would be nice to be able to put those out.

[Relequestual]

I feel that releasing updates to document seperatly is OK, but I also feel a bit uneasy. It may be intended to make this possible by splitting the spec to several documents, but it causes a problem if we proceed down that road.
Currently a json-schema document can define which draft it is using. The version of hyperschema and validation are not seperated from that.
if we updated say core and validation, without having to also update hyper-schema, that's NOT a problem. However if we were to update validation without core, or hyper-schema without core, then that version of core will have multiple versions of validation and or hyper-schema, and an implementor has no way to know whcih of those to use.

Allowing updates to the documents seperatly is fine, IF at least one of the following is true:

• An update to any triggers at the least a version bump in the overally draft as a whole.
• An update to any must always include an update to core.
• We state with each draft of core, which drafts of the other documents should be used, which will not be changable till core is updated.

Otherwise, we could run into fractions of the specification, as I've outlined above.

[Relequestual]

I'm happy to change the wording for the text relating to this issue to just say 'latest', however we should then also make clear that the metaschemas may not be the latest, and that someone looking at them should check to which draft they pertain.

[handrews]

@Relequestual I don't feel any need to rush in to independently releasing things.

I'm hoping that we can stabilize core soon and not need to update it further most of the time.

Also, there's no separate meta-schema for core. While we only list the meta-schemas as informative, for most people it is the $schema declaration that indicates which rules are in use (hence my immense frustration over a lack of a meta-schema for v5 despite several significant changes- just because v4's meta-schema probably won't choke on a v5 schema doesn't mean its correct, and it made it impossible to declare the correct vocabulary within a schema- but whatever, we'll fix it with v6).

[Relequestual]

After some discussion with @awwright on irc, my take away was the following.

• The specification section should say draft-5
• The meta-schema should state this is draft-4 currently, and draft-5 is being worked on
• The specification section should include the full draft URI name "The latest published Internet-Draft is draft-wright-json-schema-00"
• The specification section should include the date of the latest release

As an aside

• We agreed that moving to semantic versioning would lead to grater confusion, as previous versions of the draft have sometimes been backwards compatible.
• I argued that as the three documents together make up the specification, a change to any single document triggers a new release of all three docuemnts, which together for a new draft, incrementing the draft number. I'm not 100% clear if @awwright agrees on this point (but he should!)

[Relequestual]

@seagreen Do you feel #56 would resolve the issue for you?

[handrews]

The meta-schema should state this is draft-4 currently, and draft-5 is being worked on

I hope this is supposed to be "draft-6 is being worked on", as publishing a draft-6 of the specification and draft-5 of the meta-schema and leaving the meta-schema number one behind would be very confusing.

[Relequestual]

@handrews the meta-schema for draft 5 is being worked on. I expect that to be completed before the spec draft-6 documents. Perosnally, I'd like to suggest that future specs are released with meta-schemas so we don't have this lag.

Did you say you believe creating a correct meta-schema for draft-5 is not possible? If that's the case, then we need to say that in stead, somehow.

[handrews]

@Relequestual I submitted a meta-schema for draft 5 a while back and @awwright rejected it because draft 5 is already published and can't be changed, and he insisted that it does not need its own meta-schema.

I later added the meta-schema changes for draft 5 to what's now the draft 6 work, and that commit could easily be spliced out for a branch or something if we want to release a draft 5 meta-schema.

I expressed a great deal of frustration over the lack of meta-schema for draft 5 and was repeatedly told that I was wrong and should drop it, so I'm puzzled now. I thought a lack of meta-schema was a major flaw with draft 5 but my attempts to fix that were decisively rejected.

[handrews]

the meta-schema for draft 5 is being worked on

I don't even know what this means. The fix is already in master.

[Relequestual]

well... =[

the meta-schema for draft 5 is being worked on

I don't even know what this means. The fix is already in master.

If the meta-schemas are already for draft 5, and you mean on master for THIS repo, then great!

As for your previous comment... that's just bonkers and I missed that discussion. If you still have / can get at the draft 5 meta-schema, onto the website it will go! No questions... Although we shall see what @awwright says to all this tomorrow... I will make sure he sees this on irc...

[handrews]

I'll make a PR for draft 5 on this repo later today. I can easily strip out the draft 6 changes that are on master (and actually I think adding "$ref" to the meta-schema is still caught up in a PR awaiting approval for > 3 weeks now, so I can add that in for the PR on this repo).

[Relequestual]

RIGHTO!

[Relequestual]

For reference #57

[awwright]

I'd really like to figure out a different way of referring to I-D publications other than by a number we give it, because such a scheme is going to get really confusing now that the IETF has restarted numbering, and it'll get even more confusing as we publish more documents.

[Relequestual]

@awwright We've discussed this. There is no other satisfactory method. Sorry.
We can mitigate the confusion by including the current and previous versions on the website, linking clearly to which draft is which document sets. Changing the versioning system now would create a greater problem than what you're trying to solve.

[awwright]

@Relequestual And this doesn't have anything to do with the meta-schema or implementation requirements; I'm merely suggesting our references to the Internet-Draft should try to use the official IETF designation where possible - if others have to use the serial number for the collection, they can, even if it's a bit confusing.

For example, the tag is named this way: https://github.com/json-schema-org/json-schema-spec/releases

[Relequestual]

Yeah... I'm wondering if others would are happy about that... I'd have much rather it was tagged with draft-5 with a reference to the full IETF designation. Simple is best. Going back to draft 0, 1, 2, etc would be WAY more confusing. I wouldn't be supprised if others would have mentioned it if you'd asked before making the tag.

[Relequestual]

I mean, this issue exists because it's confusing and we need to be clear. If we say draft 5 = these documents on the website, I see no problem. #56 is enough for me.

[Relequestual]

Blocked because of discussion at json-schema-org/json-schema-spec#168

[Relequestual]

I decided to merge #56 as there was no further comments or discussion.

[Relequestual]

@seagreen Do you feel that #56 gives the clarification you were looking for?
If so, I'd like to close this issue, and track the fact that the meta-schema for draft-5 is missing in another issue.

[seagreen]

Looks great 🎉. Close away.