make collection+item example more self-contained

[dlax]

Follow-up on review comments in PR #464 (https://github.com/json-schema-org/json-schema-spec/pull/464/files#r148458346 and https://github.com/json-schema-org/json-schema-spec/pull/464/files#r148459558 in particular).

Currently the collection+item example section is not self-contained as it implicitly refers to a JSON Hyper Schema defined three sections above (the "thing" schema in section 9.2). I'd suggest this "thing" schema to be repeated in the collections example, or inlined in the "thing-collection" example so that one can read and understand the section as a self-contained example. Alternatively, we might add a reference to another example, but this would arguably be more disruptive.

[handrews]

@dlax I've been thinking about this and part of the decisions should be based on whether the typical reader (if there is such a thing) is likely to be reading the whole thing or using it as a reference.

If using as a reference, it should definitely be more self-contained. To some degree I want to say that the spec is not intended to primarily be a reference (rather, it is a guide for implementors), but realistically that is how people use them. I certainly use RFCs that way a lot myself.

So I am becoming more in favor of duplicating info even if it makes the document longer. Still thinking on the best way to accomplish this, and whether some things would work fine as links, and if so where the example that is linked to fits best.

No real conclusion here, just an update on my thought process to show that I haven't forgotten :-)

[handrews]

Also, if anyone has a better entity to use than "thing" that they think would be more clear, do speak up. I made the examples about "things" because otherwise I'd still be sitting with a blank screen trying to come up with the perfect concrete example.

[handrews]

@dlax It seems easy enough to copy the individual thing schema exactly as it appears earlier to be right above the thing collection schema. I'd be fine with that duplication.

I also considered moving collection/pagination up so the individual thing is not so far away, but it seems to me like the other examples are needed to explain techniques used in collection and pagination. Let me know if you think a different order of examples would work better, though. I am definitely open to rearranging them.

If we want to just copy the individual thing down, is there anywhere else where these later examples feel incomplete? I'm sold on the idea of them being self-contained at this point.

[dlax]

@handrews Yes, a plain copy would fine and enough to solve this issue.

[handrews]

@dlax well I ended up doing a lot more in #490, and since you approved that I'm going to go ahead and close this. Definitely please open a new PR with any further feedback, including if something that I pushed back on earlier now seems more applicable after #490.