add example for title/title*

[dret]

there currently is no example for how the JSON representation looks for RFC 5987-style link parameters such as title/title*. we should add such an example and we should also better describe the mapping between the native RFC 5988bis syntax and the JSON representation.

[hvdsomp]

I had deliberately left title* out because JSON requires UTF encoding, preferably UTF-8, see https://tools.ietf.org/html/rfc7159#section-8 . So, I am not sure how RFC5987's ability to specify other character encodings can/should be supported. This is, as I have mentioned, where I am on thin ice re character encoding issues.

[asbjornu]

What's the concrete use-cases for supporting encodings other than UTF-8?

[dret]

On 2017-08-03 02:13, Herbert Van de Sompel wrote:

I had deliberately left |title*| out because JSON requires UTF encoding, preferably UTF-8, see https://tools.ietf.org/html/rfc7159#section-8 . So, I am not sure how RFC5987's ability to specify other character encodings can/should be supported. This is, as I have mentioned, where I am on thin ice re character encoding issues.

the thing is that title* is not just about character encoding. it also is about language tags, meaning you can have an english title and a german title and so forth. if we want to support this as well, then we still need some way to represent more than one title, and a way how to represent the language tags. this is what the current proposal does.

[dret]

On 2017-08-03 02:21, Asbjørn Ulsberg wrote:

What's the concrete use-cases for supporting encodings other than UTF-8?

the native syntax only supports ASCII, so any non-ASCII character needs special treatment (in that syntax), which is what RFC 5987 specifies.

more importantly, the use cases that matter for JSON are about internationalization and supporting language tags, so that language variants of link parameters (such as language-tagged titles) can be represented.

[hvdsomp]

It seems to me that, in the serialization you currently propose for internationalized target attributes (e.g. title*), you allow for the provision of content in multiple, not just one language:

Internationalized link parameters use the link parameter name as their name, and their value is either a string representing the link parameter value, or an object representing one or more language tagged link parameter values. In such an object, the set of members uses a language tag <xref target="RFC5646"/> as their names, and their values are strings representing the link parameter values associated with the respective language tag.

If I am not mistaken, such functionality is neither described by rfc5987 or rfc5988bis. Actually, it seems like this would be the equivalent of providing multiple title* attributes, which is explicitly disallowed in rfc5988bis:

The "title*" link-param MUST NOT appear more than once in a given link-value; occurrences after the first MUST be ignored by parsers.

But maybe I don't understand the content model of rfc5987 correctly. Then again, I did not see any examples whereby content in multiple languages or serializations was provided in an e.g. title* attribute.

[dret]

On 2017-08-04 06:23, Herbert Van de Sompel wrote:

It seems to me that, in the serialization you currently propose for internationalized target attributes (e.g. title*), you allow for the provision of content in multiple, not just one language:

true. and that's incorrect (thanks for spotting).

If I am not mistaken, such functionality is neither described by rfc5987 or rfc5988bis. Actually, it seems like this would be the equivalent of providing multiple title* attributes, which is explicitly disallowed in rfc5988bis:

true. this means that the only facility title* provides that matters for JSON is language tagging. i think we have two options:

• keep language tagging and come up with a serialization that allows for at most one language tag (no need for an array anymore). we could keep title/title* as the names for this.

• drop language tagging and clearly state that this feature of RFC 5988bis (which seems to be mostly a by-product of an optional language tag added by RFC 5987) is not supported in the JSON serialization.

i am in favor of the second option.

[hvdsomp]

We probably need to extend this discussion (and a solution) beyond title to include the general case of extension attributes (the `token` variant). And take into account that those extension attributes can be repeatable, see #71.

[dret]

ideally, the JSON model should be coherent. but we could come up with something specific for title/title*, because we know how they are defined. for the general case it's a bit different because we cannot predict how somebody decides to define repeatable target attributes. they could also allow "folding" (like the rel="rel1 rel2" pattern) or not. we just don't know. so we should specifically write about how to handle the case when title and title* are present. as mentioned, i am in favor of dropping language tagging. for anybody in favor of other solutions, please propose concrete JSON structures.

[asbjornu]

Doesn't RFC 5988bis mention the case where title and title* are both present? If not, that seems like an omission, imho.

[dret]

On 2017-08-15 08:02, Asbjørn Ulsberg wrote:

Doesn't RFC 5988bis mention the case where |title| and |title*| are both present? If not, that seems like an omission, imho.

yes it does: https://tools.ietf.org/html/draft-nottingham-rfc5988bis-07#section-3.4.1

[asbjornu]

Thanks for the pointer. For brevity, search engines, lurkers and such:

If both the "title" and "title" link-param appear in a link, applications SHOULD use the "title" link-param's value for the "title" attribute.

So that's the processing model of duplicate title and title* attributes settled, then? The answer to:

so we should specifically write about how to handle the case when title and title* are present.

Should then be to refer to RFC 5988bis section 3.4.1, no?

[hvdsomp]

• title is not repeatable
• title* is not repeatable
• title and title* are different attributes
• both title and title* can be used on a link
• if both are present, title* takes precedence

On Aug 15, 2017, at 22:56, Asbjørn Ulsberg notifications@github.com wrote:

Thanks for the pointer. For brevity, search engines, lurkers and such:

If both the "title" and "title" link-param appear in a link, applications SHOULD use the "title" link-param's value for the "title" attribute.

So that's the processing model of duplicate title and title* attributes settled, then? The answer to:

so we should specifically write about how to handle the case when title and title* are present.

Should then be to refer to RFC 5988bis section 3.4.1, no?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[dret]

On 2017-08-15 15:04, Herbert Van de Sompel wrote:

• title is not repeatable
• title* is not repeatable
• title and title* are different attributes
• both title and title* can be used on a link
• if both are present, title* takes precedence

this is one possible design. another one is to decide that they are both the same value dealing with specific i18n issues of HTTP link headers. we could decide to not expose this specific wrinkle of the native syntax in the JSON serialization (@mnot actually recommended to go this latter way but i do not recall where at the moment).

[dret]

On 2017-08-15 14:56, Asbjørn Ulsberg wrote:

So that's the processing model of duplicate |title| and |title*| attributes settled, then? The answer to:

so we should specifically write about how to handle the case when
|title| and |title*| are present.

Should then be to refer to RFC 5988bis section 3.4.1, no?

true, iff we decide to stick with the general RFC 5987 model. #78 is discussing this issue.

[dret]

suggested resolution to this topic (based on the general approach suggested in #78, but with tweaks for the non-repeatability):

• generally speaking, handle title/title* just like any other RFC 5987 case. this means that title* becomes an array of the title itself, and an optional language tag.

• both attributes are non-repeatable, so for both the (outer) array is dropped.

native: <http://example.org/>; rel="next"; title="hallo" JSON: [ { "href":"http://example.org/", "rel":"next", "title":"hallo"

native: <http://example.org/>; rel="next"; title*="UTF-8'de'n%c3%a4chstes%20Kapitel" JSON: [ { "href":"http://example.org/", "rel":"next", "title*":["nächstes Kapitel", "de"] } ]

[dret]

this resolution is not what is currently in the published draft (-01). there title* is in line with generic RFC 5987 style attributes and thus is an array containing an array. in the resolution proposed above, title* takes into account that it is not repeatable and thus removes one of these array "levels". the resolution above seems to be a bit more in line with the handling of other predefined target attributes. any opinions?

[dret]

done.