How to handle multiple "rel" values per RFC 5988

[handrews]

@dret has been looking at this issue with respect to JSON serialization for his linkset I-D, and is going in the direction that "rel" should always be an array. We could match this (and potentially other things from the linkset work, as having JSON Hyper-Schema LDOs be compatible seems like it would be nice, see also #7 Link Attributes in JSON Hyper-Schema).

This would look like:

{
    "links": [
        {
            "rel": ["self", "canonical"],
            "href": "foos/{id}",
            "targetSchema": {"$ref": "#"}
        }
    ]
}

There are two obvious alternatives for JSON Schema:

1. Use space-separated values in a single string per RFC 5988 HTTP Link header serialization. This discards the value of JSON as a structured data format, so I'm fairly strongly against this. It looks like:

{
    "links": [
        {
            "rel": "self canonical",
            "href": "foos/{id}",
            "targetSchema": {"$ref": "#"}
        }
    ]
}

2. Accept issue Allow "$ref" for LDOs #319 and allow "$ref" for LDOs:

{
    "links": [
        {
            "rel": "self",
            "allOf": [{"$ref": "#/definitions/singleFoo"}]
        },
        {
            "rel": "canonical",
            "allOf": [{"$ref": "#/definitions/singleFoo"}]
        },
    ],
    "linkDefinitions": {
        "singleFoo": {
            "href": "foos/{id}",
            "targetSchema": {"$ref": "#"}
        }
    }
}

Of course, we could both accept "linkDefinitions" (#319) and specify that "rel" MUST be an array, as there are other use cases for "linkDefinitions". So we may want to satisfy those use cases and also be compatible with linkset serializations, which would require doing both of these things.

We could also allow "rel" to be either an array or a single value. I dislike that sort of thing, but there is a precedent with "type" where it is also true that the vast majority of uses call for only a single value. That way we could give people the option of linkset compatibility but also allow for a JSON Hyper-Schema-specific shorthand.

[dret]

it definitely would be nice to have consistent patterns across JSON models for links. but it most definitely is not necessary. just look at how HAL drives everything from the relation: then you end up with a quite different view of how to represent links.

[handrews]

@dret yeah, technically the current draft of JSON Hyper-Schema also drives everything from the relation, because we deleted "method" and didn't replace it (and I hope that we avoid replacing it directly, see #73 and IMHO more importantly #296).

[dlax]

It seems to me that one difference between JSON Schema's LDO and linkset's link definition is that the latter closely refers to RFC5988(bis) while the former redefines link object's properties. So maybe the question is whether there are use-cases for multiple "rel" values on a single object, especially since this would just be a shortcut to avoid repeating a link definition. Personally, I'd favor simplicity and explicitness over making the spec more complex just for a "shortcut". (No strong opinion though.)

[dret]

On Aug 19, 2017, at 03:38, Denis Laxalde ***@***.***> wrote: It seems to me that one difference between JSON Schema's LDO and linkset's link definition is that the latter closely refers to RFC5988(bis) while the former redefines link object's properties. So maybe the question is whether there are use-cases for multiple "rel" values on a single object, especially since this would just be a shortcut to avoid repeating a link definition. Personally, I'd favor simplicity and explicitness over making the spec more complex just for a "shortcut". (No strong opinion though.)

we had the exact same discussion for linkset JSON and decided to go with the "idiom" that people are probably familiar with because of its support in the native syntax. but you're absolutely right that it's just a shortcut and slightly complicates the representation and processing. dret/I-D#73

[handrews]

@dret, @dlax yeah, I think making it a mandatory array makes sense in the JSON linkset serialization.

For JSON Hyper-Schema, if we agree that we can use $ref for LDOs (#319), then I think that becomes the relevant "idiom" here. $ref is the accepted way to re-use JSON Schema elements, and while it is more verbose to manage than a simple array, the use case is sufficiently rare that that seems acceptable to me.

If we go that route, then I think we would also explicitly forbid multiple values in the rel string. While the current wording does not support multiple values, it's a reasonable enough inference to apply it from other serializations so I think we should address it directly.

[dret]

On Aug 19, 2017, at 11:42, Henry Andrews ***@***.***> wrote: If we go that route, then I think we would also explicitly forbid multiple values in the rel string. While the current wording does not support multiple values, it's a reasonable enough inference to apply it from other serializations so I think we should address it directly.

absolutely. it's a popular idiom/microsyntax, so it's good to address it explicitly.

[handrews]

OK, I'm going to mark this as blocked on #319, since whether we implement that has a pretty big impact on our options here.

It doesn't sound like there's anyone (yet) objecting to solving this with LDO references, if we decide to support LDO references. While an array value is definitely the right idiom in plain JSON, I think it's reasonable to consider references a suitable idiom on JSON Hyper-Schema. And if not, that will probably become more clear after we nail down #319 one way or the other.

[handrews]

Moving this out of consideration for the current draft as #319 is also deferred.

[handrews]

At this point I think the correct solution is to follow the precedent of type and allow rel to be either a string or an array. JSON Schema parsers already have to understand this, and the vast majority of links will use the string form (as is the case with type).

As noted in #124 (comment) I'm still inclined to keep links as an array rather than changing it to an object, so we do need to solve this.

Anyone have strong objections to following type here?

[handrews]

It's been more than three weeks with one upvote for following type, and no objections. I am moving to a PR. We are keeping links as an array (#124), and we are also not moving forward with any sort of $ref for LDOs at this time (#319), so this is the change that we need to make.

[dret]

tagging @hvdsomp so that he knows what's going on elsewhere...

[handrews]

Forgot to close this when #615 was merged.