w3c / w3c-api

The W3C API
https://w3c.github.io/w3c-api/
214 stars 92 forks source link

Harmonize format of rel names and use of URIs for our own relation names #47

Closed vivienlacourba closed 9 years ago

vivienlacourba commented 9 years ago

The Web Linking RFC that HAL references indicates:

Registered relation type names MUST conform to the reg-rel-type rule, and MUST be compared character-by-character in a case-insensitive fashion. (...) reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" ) LOALPHA = <any US-ASCII lowercase letter "a".."z"> DIGIT = <any US-ASCII digit "0".."9">

Our relation names don't follow that pattern we should harmonize and follow it.

Note that relation names that are not registered should be URIs (possibly shorten with CURIE) as explained in HAL's "8.2. Link relations" section and Web Linking RFC's "4.2 Extension Relation Types" section.

This proposed change only concerns rel names and does not affect JSON properties names which contain underscore characters.

IRC logs of the discussion with @deniak

<vivien> BTW regarding our recent rel renames and the registered rel names out there I wonder if we should follow the pattern of only allowing lowercase and - in rel names
<vivien> this would mean replacing our rel that currently have _ by -
<denis> +1 on harmonizing all the properties but no strong opinion on the format
<denis> dashes seem fine to me
<vivien> The Web Linking RFC that HAL references says:
<vivien> https://tools.ietf.org/html/rfc5988#section-4.1
<vivien> [[
<vivien>    Registered relation type names MUST conform to the reg-rel-type rule,
<vivien>    and MUST be compared character-by-character in a case-insensitive
<vivien>    fashion.
<vivien> ]]
<vivien> [[
<vivien>    reg-rel-type   = LOALPHA *( LOALPHA | DIGIT | "." | "-" )
<vivien> ]]
<vivien> LOALPHA        = <any US-ASCII lowercase letter "a".."z">
<vivien> DIGIT          = <any US-ASCII digit "0".."9">
<denis> so it means we are not currently HAL compatible
<vivien> not really as not all our relation names are registered ones
<vivien> but it would be better to follow that convention
<vivien> like active_charter should be called active-charter
<vivien> same for the previous/next charter link
<denis> let's discuss that with JG tomorrow
<vivien> yep
<vivien> https://tools.ietf.org/html/rfc5988#section-4.2
<vivien>    Applications that don't wish to register a relation type can use an
<vivien>    extension relation type, which is a URI [RFC3986] that uniquely
<vivien>    identifies the relation type.
<vivien>  
<vivien> in theory we should even use URIs (shorten with CURIEs) for the non registered rel names we introduced
<vivien>  
<vivien> I'll create a ticket for that
vivienlacourba commented 9 years ago

This modification has been merged and will be deployed on Monday 12 Oct in the morning.

vivienlacourba commented 9 years ago

This has been deployed. Now all relations are using lowercase and - characters.

At this stage we have decided not to use URIs for our own relation names (this would need to be introduced alongside CURIEs).