Hyper-Schema examples: wrong, confusing, or changed?

[jdesrosiers]

This example is either wrong, confusing, or significantly changes the semantics of Hyper-Schema. All of the examples look like this, so I'm concerned.

For example, if a schema is defined:

 {
    "links": [{
        "rel": "self",
        "href": "{id}"
   }, {
        "rel": "up",
        "href": "{upId}"
    }]
}

And if a collection of instance resources were retrieved with JSON
representation:

GET /Resource/

[{
    "id": "thing",
    "upId": "parent"
}, {
    "id": "thing2",
    "upId": "parent"
}]

Wrong
This Hyper-Schema and JSON Document do not match up in a meaningful way. The links apply to the array, not the items in the list. An array has no property "id" or "upId", so neither of these links will apply.

Confusing
Maybe you intended that the Hyper-Schema was a segment of the full Hyper-Schema describing this resource and that the LDO applied to each item in the list. In that case, the example is confusing and misleading.

Changed
The other option is that you changed the semantics of how LDO's work in a way that is not well documented.

A Hyper-Schema that correctly describes the JSON Document in the example would look like this.

{
    "type": "array",
    "items": {
        "links": [{
            "rel": "self",
            "href": "{id}"
        }, {
            "rel": "up",
            "href": "{upId}"
        }]
    }
}

[handrews]

Or just make the example have two instances, each of which fits the current schema. Instead of stuffing them in an array.

[awwright]

@jdesrosiers Yeah, it looks like this needs a lot of cleanup. Unfortunately Hyper-schema didn't get nearly as much love as "core" did.

The only interpretation that makes sense is it's providing an array of instances, each can be described by the schema.

The "base" keyword has the most up-to-date example in the document, does that form sense you you?

[jdesrosiers]

Yes, that one looks right.

[Relequestual]

If you think the PR doesn't "fix" this issue, please reopen.