This is a great direction. A little typo but great content. Seeing as a lot of what JSON Schema is going to be used for is CRUDy REST(ish) APIs, this example is really going to drive the point home to people doing that.

Given the significance of this example and the one enthusiastic approval, I'm going to go ahead and merge this to get it into the "final review" announcement. Obviously further comment is very much desired and welcome, and merging this does not set it in stone at all.

I agree with @philsturgeon that this example demonstrates the power of JSON Hyper Schema, however, it is very complicated and thus I suspect many people will get lost quite quickly. (I find myself lost, to be honest.)

One thing that'd help would be to leave the pagination part aside and only focus on collection+item links (plus POST semantics). Hence, the collection schema could be a simple array.

A more complete example with pagination could be in the form of a tutorial on the website.

@dlax I don't find an array example to be very compelling. For me, that's not a real-world example. Collections that are filterable or paginated/scrolling are unmanageable under hyper-schema without meta-data, and showing a "collection" that can't be filtered or paginated is not realistic.

While I don't want to make the standard a tutorial, this is THE design pattern of REST and experience tells me that few people will get it right on the first try with Hyper-Schema. I certainly did not. It uses nearly all of the LDO features in ways that are not always obvious but are crucially important.

I would definitely be interested in suggestions on how to build up to it in more steps, organize it better, or explain it better. But I think a fully functional collection (with at least one of pagination or filtering, and pagination is easier) is the most important example to have.

This gets back to the difference in how you and I see examples. I dislike small examples all over the place that break up the flow of text. What I really want to see is how you use everything together for something of real-world complexity. That is what is interesting, because it is not obvious how to do this from just reading all of the features.

@philsturgeon do you have any thoughts on this?

I would love to find a way to reach this level of example even if we break it up into more subsections.

@dlax also if you want to get into an involved discussion on how to improve this example, maybe file an issue for it? I just realized this is a closed PR.

@handrews in my opinion @dlax makes a great point. The confusion between "items" in the server response and "items" as a JSON Schema keyword is really going to throw a lot of people, but as you say documenting a bare array is going to confuse people further.

People do not generally return bare arrays for collections due to whispers of "its not secure", which is mostly a tiny vector in outdated browsers that only exists if your API supports sessions, which... ugh what.

So, we have a confusing example, with a confusion option suggested. How do we resolve this?

Renaming "items" might be a good start?

@philsturgeon we can definitely rename items. Sometimes I call it "elements", depending on whether I think the symmetry or lack of symmetry is more confusing. ̄_(ツ)_/ ̄

I'm also open to other names. "contents"? "theActualStuff"? :-P

Should this be broken into two examples? I could do it without pagination, and then add pagination.

Right on!

Some folks call it data which is pretty darn vague, or... <foo>s

I think I'll avoid "data", "results", or anything else that might look like a generic response envelope rather than something specific (so "contents" is probably out as well).

I go back and forth with "foos". If there's a well-defined domain vocabulary with rules for plurals, that works well. If not, it's better to have something standard-ish ("items" or "elements"). Of course I also don't want the examples to be a rathole of stylistic debates on API design, either.

@dlax @philsturgeon posted PR #464 to attempt to address this.

@handrews

PR #464 to attempt to address this.

That's a good step forward.

@dlax also if you want to get into an involved discussion on how to improve this example, maybe file an issue for it? I just realized this is a closed PR.

Opened #465 to discuss about pagination more specifically.