Add specification links as page on website

[adamvoss]

I thought I was done with things needing PRs here, but then I had this conversation that concerned what is and isn't in the spec (which ended up as partially a misunderstanding on my part, somewhat invalidating the reasons for this pr 🤷). This is not a perfect solution for addressing that issue, but I think it is a step in the right direction. Note: this also builds on #85 (sorry about the diff, it will become more readable after #85 is merged).

This adds the following page:

This modifies the Docs page to link to it:

The intention is that, if this is merged, the corresponding wiki page would be removed with that traffic directed to the website.

[handrews]

So you're proposing to move the old specification links from the json-schema-spec repo's wiki to the web site proper? I don't actually remember why it's a wiki page, btw.

[adamvoss]

@handrews yep, that is the overall change. In the process I made some modifications (ex. re-ordering) that I think makes it more user-friendly, and added links to the latest draft (which was largely what I was trying to accomplish).

[Relequestual]

@handrews iirc it was done as a wiki page because @awwright specifically didn't want to advertise old versions of the spec on the website (as per that screenshot), which I still feel is preferable.

Any further thoughts or specific objections @awwright ?

[Relequestual]

@vossad01 appreciate the effort your taking to look at and try to resolve issues as you see them. =]

[adamvoss]

@Relequestual What is gained by keeping them in the wiki other than preventing PR's against the list?

The Software page already advertises other versions though entries indicating what version they support. If a website user then tries to find information about one of those version on the website, they have to click a link from the Docs page either way. So with respect to navigation depth, the information is equally buried. Is there some other advantage in sending them to GitHub when they want an older version?

This makes it so the user not need to navigate to an external site to get information regarding the project the site represents, adds information about there being a draft version of the schema, and [arguably] improves usability for users who need to access an older version.

[adamvoss]

New commits pushed to include the latest changes from the wiki.

[Relequestual]

but maybe we could list in a table which functionality is provided by various meta-schemas. For people not familiar with the history of JSON Schema, this might be much more helpful than having to read through old drafts.
@awwright

Sure, sounds like an idea. But that isn't the purpose of this PR.

[Relequestual]

@handrews Can you weigh in on this one please? =]

[handrews]

I'll take a look at this and #86 today or Monday.

[handrews]

@vossad01 I know I said I'd look at this last week- my apologies. I ran into minor trouble getting ruby/bundler/jekyll set up and then other things came up at work. I haven't forgotten about this and the other PRs here.

[handrews]

@vossad01 since you commented in #86 just now that this would be easier to recreate than rebase due to the long delay and intervening changes, and since there is some debate over the solution, I'm going to close this PR so we can try again from a clean slate. Feel free to re-open if I have misinterpreted you.

@awwright @Relequestual my thought here is that we should provide some sort of acknowledgement of the ongoing significance of Draft-04 and a clear link to information about it, while emphasizing that it is (many years) outdated and implementations should move to Draft-06.

I don't think we should link to the older specifications. The only person who has shown up asking about Draft-03 inherited a very old project with unusual constraints. There's not really even anyone here who can answer questions about the intentions behind Draft-03 and any of the older drafts.

As for drafts 00-02, I've never encountered anyone who is doing anything at all with them.

Draft-03 is nearly seven years old, I think we can let it go :-) Anyone who feels like doing research on the old drafts really should have to dig with it.

I'll submit a PR with what I have in mind.

[adamvoss]

@handrews Thanks for keeping up with this! There were no merge conflicts with this PR so rebasing would only be a matter of manipulating history rather than a need for being able to merge this. Due to the presence of merge commits and unrelated branches rebasing would be more complicated than just repeating the changes manually (if a rebase were desired). The creator of an Issue or PR can only reopen if they were the one to close, so I have no power to reopen this.

I stand behind this PR as being an improvement and better than linking to a the wiki. Other improvements have also been mentioned here, which could be nice to have but none of them seem to preclude this change.

Regarding the other thread here about linking to these things at all, I really have no stake. My two cents are if something is really not worth being Internet accessible, I'd bury it in the Git history (someone can always dig it up if the need arises). If it is to be published, then the official website the best place to clarify the narrative.

[handrews]

creator of an Issue or PR can only reopen if they were the one to close, so I have no power to reopen this.

I can't tell if that means you want it re-opened or not, I'm happy to re-open if you prefer.

However, @awwright's objections still need to be addressed, and I haven't seen a resolution to that. But I'm perfectly happy to re-open this and let you and @awwright sort it out. My proposal above was an effort to split the difference by improving the linking and findability for the currently important drafts while leaving the 7+-year-old ones hard to find. But I don't feel strongly about it.

Anyway, let me know if you'd like me to re-open it and I will.

[adamvoss]

I would rather have this accepted or rejected than closed without resolution. So please reopen unless you consider it rejected.

Regarding @awwright objections, I agree with @Relequestual. The audience is not only library authors (where new implementations should use the latest draft), but also consumers of such tools who may need to reference older drafts, so old drafts should be accessible.

I may be reading this wrong but it sounds like:

Accepting of linking: @Relequestual
Against linking: @awwright @handrews

From that standpoint perhaps this is rejected; however, I will point out that rejecting this does not address the desire against linking. As pointed out above, links are still available through the website after the same number of actions with or without this PR.

[handrews]

No, it's not rejected in that sense. I honestly thought you meant it needed to be re-done based on your comment in #86, otherwise I would have left it. I really don't just go through randomly closing things on a whim :-P

I'm strongly in favor of linking draft-04

I don't see a use case for linking the older drafts, and think it will cause confusion over what implementations need to support (we actually do not want them to support anything before draft-04, and new implementations should not bother supporting draft-04 either), but I don't feel strongly about it so if you can sell @awwright on it then I'm fine with it.

[Relequestual]

@vossad01 Really apprecaite the ongoing effort on this work!

@awwright @handrews
How about some subtext along the lines of "It's strongly advised that you do not use JSON Schema prior to draft-4. If you feel this is unavoidable, please find information on really old expired drafts on the github wiki or raise an issue."?

[awwright]

@Relequestual At the very least some sort of note like that, yeah. It doesn't even need to be strongly worded, I'd say it's for historical interest, and the drafts are expired.

[Relequestual]

Great thanks. That sounds like a step towards resolving your reservations on this change.
I'm going to take this off hold, as now we just need to decide the phrasing.

@vossad01 I think we could get this change in if you remove draft 3 and previous drafts, and then create a new issue to allow us to determine the phrasing for commenting on / mentining and linking to the expired drafts wiki page.

[adamvoss]

By request (#87 (comment)), I have removed the links older than Draft 4 with the intention of allowing this PR to be merged and a new one be opened to address the older drafts.

[handrews]

I hate to say this, but I can't figure out what's up with this 30-commit change. I can't get it to show me the diff to master, which is what I want to see.

Is there any way to simplify this? rebase and force-update? re-submit? I hate to make you do even more work, but while I can see the latest commit easily enough I can't make heads or tails of what this would do if I merged it. Maybe I'm just missing something- if you know how to make it show the right diff could you paste a link?

[adamvoss]

I'll look into it tomorrow. IMO, GitHub is being extremely unintelligent with the diff. My shot-in-the-dark attempt to make it better by merging with master made it worse... now showing 49 changed files. It is showing the diff from every commit in this branch that didn't exist when the PR was opened even when the commit now already exists in the target branch :S

[adamvoss]

Hmm... force push reverting my merge fix seems to have triggered GitHub to realize 'master' has moved and thus compare this PR against the latest rather the state when this PR was opened. Now I only see two files changed. Enjoy :-)