Json-api: Clarification request: link object

[beauby]

The spec states:

an object (“link object”) which can contain the following members:

Does it mean that a link object can contain any member but it is suggested that href and/or meta are defined?

[ethanresnick]

Does it mean that a link object can contain any member

No. It means that a link object can only contain href and/or meta. That meaning comes from this part of the specification:

Unless otherwise noted, objects defined by this specification MUST NOT contain any additional members. Client and server implementations MUST ignore members not recognized by this specification.

What's missing currently, which I think may be what you're pointing out, is that we don't say whether either of those members are required when (I think) href should be required.

[beauby]

Wow, I've read the spec countless time and somehow never saw that note!
href should clearly be required. Requiring meta as well when a link is an object sounds sensible, as otherwise it is just complexity and wasted bytes for no reason.

[ethanresnick]

href should clearly be required.

I think I agree with you, even though it's technically a breaking change, because I can't imagine anyone is sending link objects right now that don't have an href. Regardless, though, this is something to work out when we clean up the link model more generally (see https://github.com/json-api/json-api/issues/1076#issuecomment-248170432).

Requiring meta as well when a link is an object sounds sensible, as otherwise it is just complexity and wasted bytes for no reason.

I don't think requiring meta will work, as it's probably too breaking a change. Moreover, I don't think requiring it would be a good idea: if link objects get other keys in the future, I can pretty easily imagining someone wanting to use a link object with href and some of the new keys, but not meta.

[beauby]

Agreed with your last paragraph. I was thinking under the assumption that there wouldn't be anything added to links in the future.

[mgold]

I was thinking under the assumption that there wouldn't be anything added to links in the future.

Perhaps the HTTP verb could be added? Only a half-serious suggestion, but the point is that it wouldn't be an absurd thing to add.

[ethanresnick]

Indeed. It's quite possible that non GET links, and much else, will be added. (See, e.g., #684.)