Host previous drafts (at least Draft 4)

[webron]

In the OpenAPI/Swagger 2.0 spec, we had pointed to specific sections of the draft 4 documentation for further information. Our mistake was that we pointed directly to the latest documentation, but I do not think that there was an option to point it to draft-4 at the time.

With the push of the latest draft (congrats!) and the replacement of the doc, our current links are all broken. We cannot simply point to the latest version because the spec does not support it.

I'm hoping you'd be willing to consider re-hosting the previous version (draft 4) at least by allowing us to link to the right sections. I do not expect that you provide direct navigation links to it, however you may want to consider a 'previous versions' section.

As a follow-up suggestion, would also suggest providing an alias link with the current draft name and not just the 'latest' to avoid future breakage as well.

[handrews]

See also #54

[Relequestual]

@webron Sounds totally reasonable and I agree!
Apologies for the long delay in reply! I think @handrews is right, this should be part of #54 .

[webron]

@Relequestual thanks. I understand you're looking for PRs on this. I imagine the draft 4 versions are in the history, so maybe I could pick those up and prepare something.

[handrews]

@webron the previous drafts are already pulled out in folders. I think we just need to link to them.

[webron]

Maybe I'm missing something but the content of the draft-xx folders is json schemas and the html version of the spec as in latest.

[handrews]

@webron Oh you mean the HTML specification, sorry, I was thinking meta-schema (probably because I've been working on that recently). Yeah, there are some XML files in the top directory, but not all, and no generated HTML. I think we would need to generate the HTML and text forms and check them in as well since I don't think we can do that sort of dynamic thing for the web site deployment.

[webron]

For draft-4 at least, we only need to pull out https://github.com/json-schema-org/json-schema-org.github.io/tree/070e1747fbadf3e94809e5dab3e987dacbc2672a/latest and put those in the right folder.

[Relequestual]

Sorry, I did think it would be the HTML, hence not just moving files to the right folders.
@webron Right, looking for PR on this one. I believe you are right! Feel free!

(On an aside... probably steer clear of draft-5 ahem. Hop over to irc and PM me if you want to chat more.)

[webron]

@Relequestual - thanks, will try to get to it in the next few days. Hopped on IRC, will idle there.

[handrews]

Note that @agebhar1 also requested Draft 3 in json-schema-org/json-schema-spec#205

[agebhar1]

The history for latest is

git log --pretty="format:%h %aI »%s«" latest

3b759fa 2016-11-06T19:12:47-07:00 »Update references to latest draft«
070e174 2013-01-31T00:41:49+00:00 »Update hyper-schema spec«
79c1a7a 2013-01-30T22:59:25+01:00 »Update latest core/validation drafts«
4ca6b0d 2013-01-25T01:08:41+01:00 »Sync latest versions of HTML specs«
4d95d97 2013-01-23T00:19:08+00:00 »Update hyper-schema spec«
8b6c818 2013-01-22T23:39:31+00:00 »Update hyper-schema spec«
5ae117b 2013-01-22T23:16:06+00:00 »Update hyper-schema spec«
8404fa0 2013-01-22T23:00:13+00:00 »Update to latest hyper-schema spec«
adef7c4 2013-01-21T01:31:50+01:00 »Latest versions of core and validation specifications«
683bea8 2013-01-20T16:15:02+00:00 »Added "documentation" section«

whereas 070e174 is the last one prior to draft-5. Unfortunately only the source for 'json-schema-core' is available (within this repository?) as draft-zyp-json-schema-04.xml. It's history is:

git log --pretty="format:%h %aI »%s«" draft-zyp-json-schema-04.xml

f643ae3 2012-09-02T17:11:23+02:00 »Draft v4: unify style«
d24139d 2012-09-02T21:17:07+02:00 »draft-zyp-json-schema-04.xml: unify style«
b5621d7 2012-08-31T12:59:49+02:00 »draft-zyp-json-schema-04.xml: remove trailing whitespaces«
0077b4d 2012-07-12T00:22:07+02:00 »Separate core schema keywords into different sections«
ba1a92c 2012-07-11T19:52:50+02:00 »Re-introduce "format" keyword, with some differences«
a8b3212 2012-05-09T17:29:06-06:00 »* Restored "integer" type. * Renamed "divisibleBy" to "mod".«
1f3275e 2011-11-29T21:20:42-07:00 »Merge git://github.com/garycourt/json-schema«
9e4df09 2011-11-29T21:20:32-07:00 »Better wording of items and their array indices«
cf45c27 2011-11-29T18:23:01-07:00 »Core changes: ...«
baa948a 2011-11-29T12:25:33-07:00 »Made core changes to draft: ...«
e22117f 2011-11-15T18:33:38-07:00 »Created initial draft-04 schemas. Added JSON Pointer to ...«
8b9ec50 2011-06-20T14:01:26-06:00 »Copied over draft 3 beautification to draft 4.«
694b44a 2011-05-18T00:33:09-07:00 »removed duplicate "required":true in price example«
60fb39c 2011-05-16T16:03:33-06:00 »Add next version«

Which of these several versions is the one that is the same as in latest (the HTML transformation)? There exists no version that equals the XML version on the the IETF site 😕 ... w.r.t. to xmldiff

$ for hash in `tac draft-zyp-json-schema-04~versions.txt`; do echo -n $hash; xmldiff -n -c draft-zyp-json-schema-04.xml draft-zyp-json-schema-04~${hash}.xml > draft-zyp-json-schema-04~${hash}.diff; echo " `wc -l draft-zyp-json-schema-04~${hash}.diff`"; done
60fb39c 1235 draft-zyp-json-schema-04~60fb39c.diff
694b44a 1235 draft-zyp-json-schema-04~694b44a.diff
8b9ec50 1779 draft-zyp-json-schema-04~8b9ec50.diff
e22117f 1828 draft-zyp-json-schema-04~e22117f.diff
baa948a 1784 draft-zyp-json-schema-04~baa948a.diff
cf45c27 1977 draft-zyp-json-schema-04~cf45c27.diff
9e4df09 1779 draft-zyp-json-schema-04~9e4df09.diff
1f3275e 1977 draft-zyp-json-schema-04~1f3275e.diff
a8b3212 1938 draft-zyp-json-schema-04~a8b3212.diff
ba1a92c 1991 draft-zyp-json-schema-04~ba1a92c.diff
0077b4d 2196 draft-zyp-json-schema-04~0077b4d.diff
b5621d7 2196 draft-zyp-json-schema-04~b5621d7.diff
d24139d 1922 draft-zyp-json-schema-04~d24139d.diff
f643ae3 1563 draft-zyp-json-schema-04~f643ae3.diff

For draft-3 draft-zyp-json-schema-03.xml@2d6f968 is the same as published on IETF

$ xmldiff draft-zyp-json-schema-03~2d6f968.xml draft-zyp-json-schema-03.xml

Sources for 'json-schema-validation' and 'json-schema-hypermedia' is missing (within this repository?).

I suggest to redirect to the versions published on IETF

• /draft-04/json-schema-core.html -> https://tools.ietf.org/html/draft-zyp-json-schema-04
• /draft-04/json-schema-validation.html -> https://tools.ietf.org/html/draft-fge-json-schema-validation-00
• /draft-04/json-schema-hypermedia.html -> https://tools.ietf.org/html/draft-luff-json-hyper-schema-00

As a side effect there's no difference on the specification hosted on IETF and json-schema.org.

What's your opinion?

[handrews]

@agebhar1 please don't close issues until after the PRs are accepted. If there turns out to a concern about the PRs we still need the issue to track further PRs or other actions.

[agebhar1]

@handrews - I can remove the GitHub magic from the PR description, no problem

[handrews]

@agebhar1 thanks! I usually just put in "addresses #whatever" for the link to avoid auto-close.

[Relequestual]

@webron Does the fix @agebhar1 proposed fix the issues for you? I wonder if it won't because the section links may be different? If that's the case, would you be able to update the section links?

[Relequestual]

@agebhar1 Thanks for your effort on this.

Which of these several versions is the one that is the same as in latest (the HTML transformation)? There exists no version that equals the XML version on the the IETF site 😕 ... w.r.t. to xmldiff

Eeek that sounds less than ideal.

To clarify, what do you mean when you say "latest"? Latest is now draft-5.

I don't know how draft-4 was released. I'd hope that for draft-5, it would be whatever is found at https://github.com/json-schema-org/json-schema-spec/releases/tag/draft-wright-json-schema-00 . It doesn't look like the previous team used the github releases functionality.

[agebhar1]

@agebhar1 Thanks for your effort on this.

My pleasure!

Which of these several versions is the one that is the same as in latest (the HTML transformation)? There exists no version that equals the XML version on the the IETF site 😕 ... w.r.t. to xmldiff

Eeek that sounds less than ideal.

@Relequestual indeed - will have a look again, what's the minimal difference is

To clarify, what do you mean when you say "latest"? Latest is now draft-5.

Did you mean this one

The history for latest is

... it's simply the directory in the root of this project

I'd hope that for draft-5, it would be whatever is found at https://github.com/json-schema-org/json-schema-spec/releases/tag/draft-wright-json-schema-00

It is:

[:88d3cff|…3] $ xmldiff draft-wright-json-schema-00.xml jsonschema-core.xml | wc -l
0
[:88d3cff|…3] $ xmldiff draft-wright-json-schema-hyperschema-00.xml jsonschema-hyperschema.xml | wc -l
0
[:88d3cff|…3] $ xmldiff draft-wright-json-schema-validation-00.xml jsonschema-validation.xml | wc -l
0

👍

It doesn't look like the previous team used the github releases functionality.

It's also my impression.

[Relequestual]

@agebhar1 Would you be able to validate if you believe #76 to be correct for draft-4 please? Would be super helpful! =]

[agebhar1]

@Relequestual sure

[agebhar1]

#76 is based on these files as @webron mentioned earlier

@Relequestual at least the JSON Schema Validation/9. Security considerations is not the same as hosted on IETF - it's missing on the github file

#65 is based on a simple HTML redirect which does not support anchors 😞

It might be possible to use the XML files from IETF to generate the HTML versions ...

[handrews]

It might be possible to use the XML files from IETF to generate the HTML versions ...

Of course! I'd completely forgotten that you can get the XML from the draft tracker :-P
We should just do that and check those in.

[agebhar1]

open #78

[agebhar1]

maybe this issue can be closed after @handrews (thanks!) has merged #78 yesterday

[Relequestual]

Smart @agebhar1 ! Super thanks for your effort on this one! (Cheers @handrews).

I think this can be closed now. @webron Does this seem satisfactory to you?

[agebhar1]

My pleasure @Relequestual

[webron]

Yup, all good! Thanks for the help, everyone!

[webron]

FYI, for anyone encountering the issue in the future, the change did break the anchors. I'll deal with for our needs.

[Relequestual]

Long may we continue good realtions between projects =D