People can't find the historical drafts v3 and v4

[agebhar1]

Maybe it's a good idea to keep historical drafts v3 and v4 from Kris Zyp et. al. within this repository to be near-complete. The current archive does only contains the (meta) schema.

[handrews]

This is being tracked over at the web site repo which is where things are actually hosted (I'm not sure why we have those archive folders here, actually) json-schema-org/json-schema-org.github.io#59 is what you want.

[agebhar1]

Thanks for the hint. It seems the schema within the archive folders here is not the same as in json-schema-org/json-schema-org.github.io ... 😕

I wonder why the (historical) draft v3, v4 is contained in the website repository and not in spec (this) repository. Shouldn't the website repository only contains the representation and not the data from the drafts itself?

[handrews]

You'll have to ask @Relequestual, who I think is away until January, as I don't quite understand the rationale for the exact split (it predates my involvement with the project).

[agebhar1]

Thx.

[Relequestual]

Sorry for the long delay. I'm not really sure why it happened that way. @awwright did the majority of the migration work.

I agree that the draft 3 and 4 versions should be in this repo... maybe we can add that to the backburner as an easy win. I'm going to re-open this issue, as I feel the XML used to build the documents should be in the archive in this repo, not just the meta-schemas.

[awwright]

@agebhar1 Old drafts become obsoleted with a successor release and shouldn't be implemented. Otherwise for historical interest, the IETF Datatracker stores old drafts at their website.

Is there any particular use you have to host the old drafts on the website?

[agebhar1]

@awwright some (at least 3) projects which support draft 4 pointing to 'latest' version (e.g. fixed it), which might be a bad idea.

The archive directory exists within this repository with the meta-schemas. This might be a bit confusing that the specs itself are not present - at least for me. @handrews referred to json-schema-org.github.io#59 which is not the right place IMHO. The website (repository) should not host any kind of specs - I would suggest to use git-submodules for that use case with a dedicated version tag. But accidentally the (XML) source for draft 4 is not in the repository which equals to IETF's hosted version (see comment).

🤔

[handrews]

I would suggest to use git-submodules for that use case with a dedicated version tag.

That would require having the old versions in the repo and tagged. For whatever reason (I was not around) when the new repos were created the old change history was abandoned.

[Relequestual]

Old drafts become obsoleted with a successor release and shouldn't be implemented. Otherwise for historical interest, the IETF Datatracker stores old drafts at their website.
@awwright

That maybe how you feel, but that doesn't work out in reality, where people are actually wanting to use JSON Schema.
When draft-6 is release, everyone should immediatly no longer write draft-4/5 schemas, and use draft-6? With what library support? It's taken FOREVER to see draft-4 support in Perl, and even now it's not as good as it should be. Sometimes people have to use what they need to use.

For whatever reason (I was not around) when the new repos were created the old change history was abandoned.
@handrews

I really don't know how this happened. I wish it wans't the case =[

@agebhar1 I'm all for getting this fixed. I DO see it as an issue.

[awwright]

That maybe how you feel

Well it's not merely a feeling, that's standard IETF process, it's literally written into every single page of the documents. To post for this thread:

Expires: August 4, 2013

Further:

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

This is not normally an issue for standards documents, but I suspect this keeps popping up for JSON Schema because of how the process was treated in the past.

The IETF does actually remove expired Internet-Drafts from their FTP server and public index, leaving copies available only on the Datatracker for historical interest.

When draft-6 is release, everyone should immediatly no longer write draft-4/5 schemas, and use draft-6?

I don't expect people to write documents making use of features that nobody implements, by design it's supposed to be mostly reverse-compatible.

And it's perfectly fine for implementations to add support for old features -- but they're doing it to make sure they support old JSON Schema documents, not because it's written into an expired I-D.

---

The website (repository) should not host any kind of specs

The only authoritative version of the specs are the plain text files as published by the IETF. These documents are traditionally distributed by hand, so there's no canon website for them, but copies are distributed through the IETF website, the IETF Datatracker, and the RFC Editor (for RFCs) -- and json-schema.org.

The json-schema.org website is a perfectly reasonable place for the specifications, it's nothing more than a mirror just like the IETF provides. An HTML formatted version is provided, however this version is non-normative.

The spec repository is a source repository, which has one job, and that is for tracking change control for the next release of the document. Storing old drafts would be akin to storing every public/tagged build of a software program in version control.

The meta-schemas are slightly different, in that unlike the I-Ds, they do not expire, and remain fair game for any current JSON Schema implementation or document to reference. So they all get stored in the repository.

This issue doesn't impact the specification in any way, so I'll close it out in favor of the mailing list or website tracker.

[Relequestual]

@awwright Your comment highlights our difference of view on what this repo, and what the whole project actually IS. You seem to see JSON Schema as ONLY a IETF Internet Draft. I see it as more than that, and therefore this repo as more than that also.

The repo readme even says...

This repository contains the current, and historical, JSON Schema specifications.

While it contains the old meta-schemas, it should also contain the old specification.
What I meant was, it's your feeling that JSON Schema, and this repo, is ONLY the I-D, and nothing more. That's simply not the case, and I'm not alone in feeling that way.

---

And it's perfectly fine for implementations to add support for old features -- but they're doing it to make sure they support old JSON Schema documents, not because it's written into an expired I-D.

I don't see any difference in those two statements your comparing. How is someone to know how to build support for old JSON Schema documents if they are unable to find the expired I-D?

---

Good luck on the conference BTW! We may have our differences, but we're all on the same team here! I really hope you don't feel I write agressivly or aggravatingly. It's always very difficult with these international collaboration projects!

[Julian]

For better or worse, people will continue to need to implement both draft 3 and draft 4 for the foreseeable future unfortunately.

[awwright]

The README.md was copied as-is from the old repo... we should probably modify that if it's causing confusion. The repository description just says "The JSON Schema I-D sources".

In short, it's not the job of this repository to publish or archive I-Ds, that's what the IETF Datatracker is for. (If we REALLY want to host these materials on GitHub for some reason, we can create a new repository.)

Thanks for the feedback as always!

[awwright]

Also, sorting through other WG efforts, I can only really find one example from the HTTPbis WG where they stored past revisions, in the http1.1bis repository. It appears they were actually doing this to be able to diff changes with the original RFC2616. It doesn't appear to be a use case we need (or there's probably a better way to do it), and none of their other work does anything similar.

I'd like to hear a really compelling reason for doing it differently before giving this repository more responsibilities beyond "sources for the work in progress".

[Relequestual]

I'm happy for it to be in a seperate repo and modify this repos readme accordingly.

I think the problem is that HTTP is established, so there's less reason to look at previous versions / drafts. Have you been able to find any specifications looking to be a Working Group candidate specification who host their work on github?

Based on your last two comments, I think we should add a note to the readme which says this repo is not authoratative, and in stead people should look at the draft documents which are linked to from the wiki page.

On an aside... I really really like the HTTPbis WG website document layout... http://httpwg.org/specs/rfc7540.html - Could we pinch that? I realise that's more an issue for the website repo... =]

[agebhar1]

The spec repository is a source repository, which has one job, and that is for tracking change control for the next release of the document. Storing old drafts would be akin to storing every public/tagged build of a software program in version control.
@awwright

Yes - that's a NO GO to store generated artefacts within a version control system. The last draft was tagged which I really like. So it's possible to link/refer to a specific draft and 'solves'

How is someone to know how to build support for old JSON Schema documents if they are unable to find the expired I-D?
@Relequestual

in my opinion. The commit log is the history with all refinements to a published RFC.

Based on your last two comments, I think we should add a note to the readme which says this repo is not authoratative, and in stead people should look at the draft documents which are linked to from the wiki page.
@Relequestual

I support it too.

On an aside... I really really like the HTTPbis WG website document layout... http://httpwg.org/specs/rfc7540.html - Could we pinch that? I realise that's more an issue for the website repo... =]
@Relequestual

... it's up to you 😄 to open an issue - btw. I can offer support

[awwright]

Could we pinch that?

@Relequestual Very likely yes. It looks like they're using an XSLT transformation to generate it from RFC XML, instead of xml2rfc. I'll let you take care of that though... =]

[agebhar1]

@awwright ... I think it's these ones

[Relequestual]

@agebhar1 Thanks for looking into it. I'll see if I can remember to file a new issue over at the website repo... I'm really stretched for time right now =[

[Relequestual]

@awwright I see your point. It wouldn't be an issue if we had previous versions tagged (which is no ones fault here).

I'm going to re-open this issue but rename it. I think we still need to work out a resolution.

[Relequestual]

I think as a solution, we should do the following.

• Remove the archive folder
• Update the readme to direct people to the wiki page when looking for previous versions

I'm happy to do the work on this one.

My alternative solution, felt like a heck of a lot more work for some unkown gain. This repo doesn't contain the history pre draft-4... that's just how it is.

[agebhar1]

I'll see if I can remember to file a new issue over at the website repo... I'm really stretched for time right now =[
@Relequestual

... There's no rush. I'm happy to work on this for a draft/PR.

My alternative solution, felt like a heck of a lot more work for some unkown gain. This repo doesn't contain the history pre draft-4... that's just how it is.

Based on the analysis I think the published draft 4 version (XML from IETF) must be between two commits - by date and 'minimal edit distance'.

[awwright]

Honestly I couldn't even tell you how I initialized this repository, I think I downloaded the XML sources from the IETF Datatracker but iirc they don't exactly match, and they don't match anything in the old repository either. It might have been a file passed around by hand.

It doesn't matter at this point though, what's authoritative is what's published by the IETF.

I think at one point I was going to store rendered I-Ds in archive/, but realized that's silly and/or redundant and never got around to it. But I do think we need the meta-schemas in there. If the "archive" name is misleading we can consider renaming it, but I think it's perfectly fine the way it is.

[handrews]

We host the archived meta-schemas on the web site. There's no need to keep extra copies over here, it should behave like the spec and just have its current state in this repo (tagged for releases as needed). Let's be at least a little bit consistent.

[Relequestual]

@agebhar1 Do you feel the addition to the readme is enough to close this issue?

[agebhar1]

@Relequestual Yes it feels much better, maybe the archive should be deleted as suggested by yourself and @handrews

[adamvoss]

Based on the analysis I think the published draft 4 version (XML from IETF) must be between two commits - by date and 'minimal edit distance'.

@agebhar1 The analysis link is dead, but the issue with finding the commit was probably that the commit does not exist on the master branch. It appears to be 7f5ecac on the next branch. (See the *.xml files under 'proposals/'). Unless I made a mistake, those draft-04 files have an exact match with the published drafts on IETF.