Rework collection example for clarity #490
Conversation
* Restate the item resource, including the newly added "collection" link. * Remove some of the more complex discussions that weren't needed to introduce the key patterns and challenges. * Make pagination and first-item-creation subsections, and put pagination first. * Write creation guidance as if it generally works, and leave the doubts to the crefs. * Generally improve the wording and flow. Hopefully.
jsonschema-hyperschema.xml
Outdated
| are introduced. | ||
| </cref> | ||
| There are two "item" links, one for each item in the "elements" array. | ||
| Unilke the "self" links, these are defined only in the collection schema. |
There was a problem hiding this comment.
I swear I ran the spell checker! Repeatedly! Argh... I need to find an intelligent spell-checker for XML in vim that I can just leave on instead of the convoluted filetype switching that I do to get the regular one to work at all.
jsonschema-hyperschema.xml
Outdated
| </cref> | ||
| </t> | ||
| <t> | ||
| Let's add a link for this collection to the entry point schema, including |
There was a problem hiding this comment.
Might be worth adding a reference to the "entry point schema" which is currently defined in section 9.1 (we are in section 9.5.1).
|
@handrews See also handrews#4 spotted while reading again these examples. (Now that they are clearer, I pay more attention to details!) |
replace href* keywords by template* in collections example
More review feedback on the collection example.
|
I'm going to go ahead and merge this b/c of the approval plus I accepted the suggested PR, and the remaining fixes are trivial and build passed. And more importantly, anyone reading the pre-publication review materials has no doubt been confused. |
gregsdennis
added
clarification
Addresses #478.
The first commit is a few trivial typo fixes outside of the collection example.
It's best not to review the 2nd commit directly given the extent of the reworking.
Just build it and read it as an entire new example. It was not reworked in anything
remotely resembling discrete steps, and I wouldn't even know where to start to split it.
@dlax note that several of the output URIs in the main example were flat-out wrong.
As we saw with the older tree example before the big rewrite, if you can't understand
an example it's quite likely not just badly organized but wrong. I'll have to remember
to consider that more closely. This is part of the problem of a spec with no implementation;
I can't just test it out.
Anyway, here are the main changes:
link.
needed to introduce the key patterns and challenges.
pagination first.
doubts to the crefs.
Note the references to issue #421, which I have to update with some of the things
I figured out while doing this.