"description" in the LDO

[handrews]

The LDO has "title" but not "description". When you think about the LDO in RFC 5988 or similar terms, this makes sense. But LDOs can easily support much more information than most link descriptions.

In my experience, most schema authors expect "description" to be present in the LDO as well and used by documentation tools. That doesn't violate any aspect of JSON Hyper-Schema, but I think it should be official as it is the obvious expected behavior within a JSON Schema (rather than RFC 5988) context.

[handrews]

Paging some hypermedia users (off the top of my head, apologies for missing anyone) @awwright @geemus @seagreen @dret @dlax any thoughts on this? I see @jdesrosiers gave it a thumbs up. This should be a pretty simple yes or no, I hope.

We use this extensively in Cloudflare's documentation tool. I'd suggest the API Doc vocabulary, except this exactly parallels "description" in the validation vocabulary so it seems to belong in the spec proper.

[dret]

On Aug 19, 2017, at 01:20, Henry Andrews ***@***.***> wrote: Paging some hypermedia users (off the top of my head, apologies for missing anyone) @awwright @geemus @seagreen @dret any thoughts on this? I see @jdesrosiers gave it a thumbs up. This should be a pretty simple yes or no, I hope.

RFC 5988bis does not have a description target attribute so linksets don't have it. but it's a very reasonable idea and seems to easily fit into the RFC 5988bis model as an extension target attribute. the linkset JSON syntax supports the same extensibility that the native syntax supports.

[geemus]

LGTM

[handrews]

Added with #353.