Fix a lot of id/ref/dereferencing problems

[awwright]

Relevant issues seem to be #14 #20 #21 #22

Rendered version of json-schema-core at 3cbfc8b is jsonschema-core.txt

(old version: jsonschema-core.txt)

[awwright]

Merging this so I can proceed forward with some other timely things, it doesn't seem there's any problems so huge we'd have to backtrack on everything here.

[sgpinkus]

Sigh.

[epoberezkin]

@awwright I don't understand why this change was merged without discussion and review.
It introduces changes that I disagree with (and @sam-at-github too as it seems).
It is disappointing that you treat the standard as if it were your own private project.

[awwright]

@epoberezkin There's been eight issues about this over multiple projects for over a year, and this PR represents my best understanding of the resolution that also fits our "maintain draft-04 meta-schema compatibility" requirement for the latest I-D release. This doesn't mean the end of being able to improve the I-D, If you have specific language you'd like to contribute, even against the current master or language introduced in this PR, you're welcome to submit it.

[epoberezkin]

ok, I will work on the suggestions for this specific issue.

In general, I think it would put quite a few people at ease and will help engaging them as contributors to the standard, rather than alienating them, if we'd agree on and follow some process for the changes in the standard (maybe some panel vote resulting a wider community vote if some qualified majority - 70%? - cannot be reached?).

Understanding that there will be some discussion and the process would make people feel that their opinion matters and will be taken into account, so their time spent on conversation is not wasted. It may slow down the change but it would make the standard more stable and attractive to adopt. What do you think? @awwright @handrews @Relequestual @fge @sam-at-github

The problem with this PR, for example, is that it contains too many changes to approve them all together; it could have been split into several changes and reviewed/approved independently.

[handrews]

In general, I think it would put quite a few people at ease and will help engaging them as contributors to the standard, rather than alienating them, if we'd agree on and follow some process for the changes in the standard.

I agree. They hyper-schema changes for v5 were pushed through incredibly quickly. Some of us are still trying to understand them even though we were very actively involved in the project's discussions that week. As happy as I am that there's a new draft, it had been more than three years so it probably could have waited a few more weeks to get a bit of community buy-in.

I think there still needs to be one or at most two people who have to make the call, and I'm certainly fine with @awwright being that person. I've been part of projects where nothing happens because there's insistence on accommodating everyone's input, but one or more people consistently dig in and derail attempts at resolution. I don't want to see that happen here, even if it means I don't get what I want. We'll probably all have our moments of being the outlier and needing to get over it.

But the process of getting from here to v6 is not clear to me, and the experience of getting v5 out the door makes me nervous about how disagreements will get resolved, or even noticed.

[epoberezkin]

@handrews:

I think there still needs to be one or at most two people who have to make the call, and I'm certainly fine with @awwright being that person.

I think it is what happens now, I don't think 1-2 is enough.

I've been part of projects where nothing happens because there's insistence on accommodating everyone's input, but one or more people consistently dig in and derail attempts at resolution.

That's why I'm saying there should a panel of say 7-9 people with 70% (rather than 100%) consensus being enough to approve anything. But if the panel cannot get 70%, then there should be a wider vote (where a simple majority is ehough) I think.

[Relequestual]

I personally have attempted to suggest a more fomal approach for developing the standard going forwarded before, but @awwright didn't agree. I can't remember the specifics.

I've been a little unhappy with the rate at which the new draft has come through, which hasn't alowed people or the community to review items. I raised this before, but @awwright wanted to get it finished and published before an IETF event (again, I forget the specifics).

On the other hand, @awwright is doing the majority of the work here, and has put a lot of work into accomodating others changes. Ultimatly, anyone can set up a new repo and publish a new IETF draft requesting comments. Consider the fact that despite the community taking up previous drafts as stable versions and using them in production, it IS still ONLY a DRAFT, and subject to feedback and comments. While various people may not agree with changes introduced in draft 5, or with how they were introduced... it is a draft and subject to feedback and comments.

I expect @awwright will acknowledge that maybe the release of this draft was time constrained, but he felt it was in the best interest of the project to get it done before said event. Although he (I believe) wouldn't want to see a panel or a formal process beyond the general consensus model, if the community wants it, then we should do it. I'd be happy to be part of any such panel, but I also appreciate I'm not activly developing parts of a project which use JSON Schema, and I don't understand all aspects fully (but I guess who does?).

Let's not get the wrong end of the stick here, @awwright has done a fantastic job! =]

[handrews]

I generally agree with @Relequestual . I'm not bothered by lack of perfection in the last draft, just that there was no time to even realize that there was a major and incompatible change in hyper-schema. As @jdesrosiers noted, it explicitly goes against the way it was in draft 04 and breaks every hyper-schema tool that relied on "method" being the actual HTTP method as was made very clear in draft 04.

That said, I don't think it was @awwright 's intention to covertly break a bunch of stuff without us noticing. It just worked out that way, and we can all learn from it and move on.

If there is a panel, I would like to be a part of it, or understand what the requirements for being a part of it are so that I can see how I can meet them. But I do not, at this time, feel the need to push for such a panel.

I would just like more transparency on what will trigger the publication of the next draft, when that will be happening, and more clarity on how a thing gets in or gets definitively rejected. When is it appropriate to submit a pull request for an issue that seems to be more or less accepted? That sort of thing. I don't think @awwright or anyone else is trying to make that difficult, but now that we have several people very active with the project, clarifying this stuff will help all of us.

As a related concern, @Relequestual do you have write access to the repo? Otherwise I am nervous that @awwright is the only active person with write access, which both sets us up for another abandoned repo scenario and also means there is no effective avenue for appeal if a substantial number of people are in disagreement with the one person who can do anything (it doesn't matter who that person is or how well they are doing, that is always a concern). I know Julian has access, but he has made clear that he no longer has time for this project (I don't know if that's permanent or if he intends to come back, but right now he's effectively not involved).

I would like for there to always be two active people who have the technical permissions necessary to run the project at all times. I'm not lobbying to be one of those people- I'd nominate @Relequestual if he doesn't have that role already.

[handrews]

Ultimately, anyone can set up a new repo and publish a new IETF draft requesting comments.

Forgot to address this. While it's technically an option, it's extremely unappealing to fork and have two competing branches of the project. It's one thing if there's agreement here that it's worth publishing an alternative and seeing what sort of feedback each gets, but otherwise that's a very hostile move with no clear end game. Everyone else then has to choose which to work with or figure out some way to get their ideas into both lines of work.

I'd personally rather limit my hostile moves to disappointingly snarky responses that I regret the next day :-P

[awwright]

Thanks @Relequestual. That pretty much covers everything I could have said...

I-Ds are not standards and are not supposed to be cited by standards, they are documents published for the sole purpose of collecting feedback, which is why I published the new I-D as soon as possible. We can keep iterating fixes and features.

The only thing I recall disagreeing with @Relequestual with is if we should merge the documents back together... there might be a good reason to do it, but I at least wanted to see where the current approach takes us (that is, defining the media type semantics separately from the vocabulary). HTTP did the same thing, after all.

We've got the GitHub org at the best place we can take it, and we've poured tons of energy into trying to fix the problems that have cropped up around GitHub. We've got plenty of people with owner access, including @Relequestual.

[Relequestual]

@handrews

As a related concern, @Relequestual do you have write access to the repo? Otherwise I am nervous that @awwright is the only active person with write access

As @awwright pointed out, yes, I do have write access to the repo, and co onwership of the org. I'm going to have less time in the future, but I can promise I'll never abandon the community. I'd have to get hit by a bus not to pass over control.

[Relequestual]

I-Ds are not standards and are not supposed to be cited by standards, they are documents published for the sole purpose of collecting feedback, which is why I published the new I-D as soon as possible. We can keep iterating fixes and features.

I know this and agree. Been thinking... Maybe we should, as a community, declare draft 4 as "stable", and note, on the website and in the repo readme, that the community intends to be rapidly developing new drafts now, and none of them should be considered "complete" or functional, and therefore should not be developed upon.

Without such a warning or note on both the repo and the site, there's going to be a LOT of confusion around now you released what is effectivly draft 5. I actually think it's our duty to the community to make this clear.

The only thing I recall disagreeing with @Relequestual with is if we should merge the documents back together... there might be a good reason to do it, but I at least wanted to see where the current approach takes us (that is, defining the media type semantics separately from the vocabulary). HTTP did the same thing, after all.

I have no strong preference for this. I only brought it up because previous authors of draft 4 felt that in retrospect it was an unhelpful move.

It's difficult to balance the needs of making structured correct formal documentation, and making documentation and notes that the community can use and understand.

[awwright]

@Relequestual Let's open a new issue for this concern, there's a few different ways we could handle it. The latest draft is, by and large, supposed to be a clarification of draft-04 behavior, without changing anything (or at least, minimum required changes to align with behavior of published standards). I'll be working on the website today, to update things and publish a reference guide for schema authors.

[Relequestual]

Good call. I'll make an issue monday morning (probably) and see what the community think.
On an interesting note, I've seen one library which supposidly supports draft 5... or at least some of the proposals they have picked up on. avj I believe.

[epoberezkin]

I've seen one library which supposidly supports draft 5... or at least some of the proposals they have picked up on. avj I believe.

Yes: https://github.com/epoberezkin/ajv

Should probably be renamed to v6 now...