CURIE names for link relations

[dret]

the spec should maybe have stronger wording about what a link relation's identifier really is. when a HAL document uses CURIEs, does that mean that all link relations (in embedded resources as well) MUST be interpreted as CURIEs and this effectively are URIs? that would make embedding HAL relatively brittle since the context then completely changes the interpretation of link relation values. what about overriding CURIEs in embedded HAL (possibly at multiple levels)? is that allowed and does it "black out" the CURIEs of the outer context? like any namespacing mechanism in nestable formats, these things get complicated and have nasty side-effects (the worst one being that interpreting HAL now is not context-independent anymore). the behavior around CURIEs probably needs more precise language and processing rules.

[mikekelly]

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again.

My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources.

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time.

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so

"foo:bar" != "https://foo.com/rels/bar"

(ie. the can't be used interchangeably)

On Sun, Mar 26, 2017 at 12:43 PM, Erik Wilde notifications@github.com wrote:

the spec should maybe have stronger wording about what a link relation's identifier really is. when a HAL document uses CURIEs, does that mean that all link relations (in embedded resources as well) MUST be interpreted as CURIEs and this effectively are URIs? that would make embedding HAL relatively brittle since the context then completely changes the interpretation of link relation values. what about overriding CURIEs in embedded HAL (possibly at multiple levels)? is that allowed and does it "black out" the CURIEs of the outer context? like any namespacing mechanism in nestable formats, these things get complicated and have nasty side-effects (the worst one being that interpreting HAL now is not context-independent anymore). the behavior around CURIEs probably needs more precise language and processing rules.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/mikekelly/hal_specification/issues/33, or mute the thread https://github.com/notifications/unsubscribe-auth/AADZ5mhIBZI8RDfqMpzNExNZfiPo0DR-ks5rpk9QgaJpZM4MpZqm .

-- Mike

http://twitter.com/mikekelly85 http://linkedin.com/in/mikekelly123

[dret]

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources.

this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time.

not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so "foo:bar" != "https://foo.com/rels/bar" (ie. the can't be used interchangeably)

absolutely. imho, any qname should be flagged as syntax error if it is not accompanied by a CURIE declaration. and the HAL processing model has to clearly state that CURIE resolution always MUST be done, regardless of whether clients are interested to dereference the link relation URI or not. without that, link relations simply aren't well-defined.

[mikekelly]

On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde notifications@github.com wrote:

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources.

this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

That is a happy accident but if we make it explicit I would prefer to make this a SHOULD not a MUST.

ie. those validators should raise it as a warning not an error

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time.

not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Actually, no. And this is one of the reason I with I never used "CURIE" and just called them "relation templates" or something.

The reason is fairly simple: I don't want to layer on processing rules which supercede the basic processing rules of JSON. The reason is because I want to protect naive clients which hardcode against the unexpanded string.

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so "foo:bar" != "https://foo.com/rels/bar" (ie. the can't be used interchangeably)

absolutely. imho, any qname should be flagged as syntax error if it is not accompanied by a CURIE declaration. and the HAL processing model has to clearly state that CURIE resolution always MUST be done, regardless of whether clients are interested to dereference the link relation URI or not. without that, link relations simply aren't well-defined.

I actually forgot to include the CURIE declaration, even with that I still don't want the two to be considered equivalent.

Cheers, M

[mikekelly]

FWIW - I explicitly don't include the CURIE declaration in embedded resources.

We only have one, consistent, curie declaration for all our resources, so it seemed like extra bloat to duplicate the curie on every embedded resource, and I'm not sure I would want that to be required. (We do of course have the curie declared in the resource which has these additional cure-less embedded resources.)

-A Andrew Kuklewicz

On Mon, Mar 27, 2017 at 3:59 PM, Mike Kelly mikekelly321@gmail.com wrote:

On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde notifications@github.com wrote:

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources.

this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

That is a happy accident but if we make it explicit I would prefer to make this a SHOULD not a MUST.

ie. those validators should raise it as a warning not an error

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time.

not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Actually, no. And this is one of the reason I with I never used "CURIE" and just called them "relation templates" or something.

The reason is fairly simple: I don't want to layer on processing rules which supercede the basic processing rules of JSON. The reason is because I want to protect naive clients which hardcode against the unexpanded string.

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so "foo:bar" != "https://foo.com/rels/bar" (ie. the can't be used interchangeably)

absolutely. imho, any qname should be flagged as syntax error if it is not accompanied by a CURIE declaration. and the HAL processing model has to clearly state that CURIE resolution always MUST be done, regardless of whether clients are interested to dereference the link relation URI or not. without that, link relations simply aren't well-defined.

I actually forgot to include the CURIE declaration, even with that I still don't want the two to be considered equivalent.

Cheers, M

-- You received this message because you are subscribed to the Google Groups "HAL Discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss+unsubscribe@googlegroups.com. For more options, visit https://groups.google.com/d/optout.

[mikekelly]

The challenge with that processing model is we then have to deal with precedence and the complexity goes up.

Sent from my phone

---

From: hal-discuss@googlegroups.com hal-discuss@googlegroups.com on behalf of Andrew Kuklewicz kookster@gmail.com Sent: Tuesday, March 28, 2017 2:27:42 AM To: hal-discuss@googlegroups.com Cc: mikekelly/hal_specification Subject: Re: [mikekelly/hal_specification] CURIE names for link relations (#33)

FWIW - I explicitly don't include the CURIE declaration in embedded resources.

We only have one, consistent, curie declaration for all our resources, so it seemed like extra bloat to duplicate the curie on every embedded resource, and I'm not sure I would want that to be required. (We do of course have the curie declared in the resource which has these additional cure-less embedded resources.)

-A Andrew Kuklewicz

On Mon, Mar 27, 2017 at 3:59 PM, Mike Kelly mikekelly321@gmail.com wrote:

On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde notifications@github.com wrote:

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources.

this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

That is a happy accident but if we make it explicit I would prefer to make this a SHOULD not a MUST.

ie. those validators should raise it as a warning not an error

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time.

not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Actually, no. And this is one of the reason I with I never used "CURIE" and just called them "relation templates" or something.

The reason is fairly simple: I don't want to layer on processing rules which supercede the basic processing rules of JSON. The reason is because I want to protect naive clients which hardcode against the unexpanded string.

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so "foo:bar" != "https://foo.com/rels/bar" (ie. the can't be used interchangeably)

absolutely. imho, any qname should be flagged as syntax error if it is not accompanied by a CURIE declaration. and the HAL processing model has to clearly state that CURIE resolution always MUST be done, regardless of whether clients are interested to dereference the link relation URI or not. without that, link relations simply aren't well-defined.

I actually forgot to include the CURIE declaration, even with that I still don't want the two to be considered equivalent.

Cheers, M

-- You received this message because you are subscribed to the Google Groups "HAL Discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss+unsubscribe@googlegroups.com. For more options, visit https://groups.google.com/d/optout.

-- You received this message because you are subscribed to the Google Groups "HAL Discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss+unsubscribe@googlegroups.com. For more options, visit https://groups.google.com/d/optout.

[dret]

On Mar 28, 2017, at 18:43, Mike Kelly notifications@github.com wrote:

The challenge with that processing model is we then have to deal with precedence and the complexity goes up.

this issue is not so much about a specific design but about the fact that currently, this feature is not well-defined.

[dret]

On Mar 28, 2017, at 04:00, Mike Kelly notifications@github.com wrote:

On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde notifications@github.com wrote:

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources. this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

That is a happy accident but if we make it explicit I would prefer to make this a SHOULD not a MUST. ie. those validators should raise it as a warning not an error

if you claim to support RFC 5988, you cannot relax its syntax requirements. if you do, you no longer use RFC 5988 web linking.

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time. not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Actually, no. And this is one of the reason I with I never used "CURIE" and just called them "relation templates" or something. The reason is fairly simple: I don't want to layer on processing rules which supercede the basic processing rules of JSON. The reason is because I want to protect naive clients which hardcode against the unexpanded string.

proper scoping needs processing rules. one way or the other (inheriting when nesting or not), the spec has to tell people how it works and they have to implement it accordingly. no processing rules simply means a not well-defined spec.

Related to this is that (imo) we need to make it explicit that curies do not affect the processing of identifiers so "foo:bar" != "https://foo.com/rels/bar" (ie. the can't be used interchangeably)

absolutely. imho, any qname should be flagged as syntax error if it is not accompanied by a CURIE declaration. and the HAL processing model has to clearly state that CURIE resolution always MUST be done, regardless of whether clients are interested to dereference the link relation URI or not. without that, link relations simply aren't well-defined.

I actually forgot to include the CURIE declaration, even with that I still don't want the two to be considered equivalent.

very good. but then people can define different prefixes for the same CURIE, use those interchangably, and the spec has to make sure these values are always interpreted to mean the same.

if iam using a:rel and b:rel in HAL, and a and b are declared as the same URI, then all implementations MUST treat a:rel and b:rel as the same link relation. that makes sense. but it does not work without processing rules.

[mikekelly]

On Tue, Mar 28, 2017 at 1:59 PM, Erik Wilde notifications@github.com wrote:

On Mar 28, 2017, at 04:00, Mike Kelly notifications@github.com wrote:

On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde notifications@github.com wrote:

On 2017-03-27 12:42, Mike Kelly wrote:

Fair point, it's come up a few times. I've copied in the hal-discuss mailing list, I think we should discuss this again. My instinct is that curies should be scoped to the resource and do not get inherited by embedded resources. this definitely is the easiest scoping rule to come up with. it means that CURIE declarations need to be repeated in every resource, standalone or embedded. it also means that "HAL validators" should be strict in flagging undeclared prefixes when they encounter link relation values using qname syntax (per RFC 5988 link relation names are not allowed to contain colons, which makes it easy to distinguish valid link relation type names and qnames).

That is a happy accident but if we make it explicit I would prefer to make this a SHOULD not a MUST. ie. those validators should raise it as a warning not an error

if you claim to support RFC 5988, you cannot relax its syntax requirements. if you do, you no longer use RFC 5988 web linking.

Nope, no intention to relax 5988. Just want a curie mechanism that is not too dictatorial, if a curie can't be expanded it's not really the end of the world - and because we'd be introducing these rules over the top of existing implementations I don't want to place them into a broken state.

The reason I wasn't losing sleep over this is that the intention all along with curies was to simply act as a way to make the relation identifiers more readable. So curie resolution is important more design-time tooling like browsers, not run time. not really because link relations must be resolved to their actual values and that critically depends on CURIE declaration and clear processing rules, right?

Actually, no. And this is one of the reason I with I never used "CURIE" and just called them "relation templates" or something. The reason is fairly simple: I don't want to layer on processing rules which supercede the basic processing rules of JSON. The reason is because I want to protect naive clients which hardcode against the unexpanded string.

proper scoping needs processing rules. one way or the other (inheriting when nesting or not), the spec has to tell people how it works and they have to implement it accordingly. no processing rules simply means a not well-defined spec.

Obviously, my point was that the processing rules we define should not supercede the basic processing rules of JSON.

In other words, the wording shoudl explicitly state that changing the name of the curie represents a breaking change regardless of if the expanded URL remains the same. i.e. "foo:bar" != "baz:bar" even if foo == baz

[dret]

On 2017-03-28 21:25, Mike Kelly wrote:

if you claim to support RFC 5988, you cannot relax its syntax requirements. if you do, you no longer use RFC 5988 web linking. Nope, no intention to relax 5988. Just want a curie mechanism that is not too dictatorial, if a curie can't be expanded it's not really the end of the world.

sounds good, but then what is it? if i have a:rel and a is defined as http://example.org/ then the link relation is http://example.org/rel. if the prefix a is not defined, then what is the link relation? a:rel? that would be syntactically invalid. just rel? then the spec has to say that an undeclared prefix is equivalent to a null prefix.

most languages using prefix declarations and references require referenced prefixes to be declared. if not, you usually end up in special case hell, or with a bunch of non-interoperable implementations.

• and because we'd be introducing these rules over the top of

  existing implementations I don't want to place them into a broken state.

since the spec is not well-defined as it is, people have made up their own rules (such as with scoping). by making the spec well-defined, you will break some implementations. that's unavoidable. the tricky part is to figure out which ones to break, and to make sure that new guidance makes sure this doesn't happen with new implementations.

what usually helps a lot are test cases that look at corner cases and say how these have to be interpreted. that illustrates a well-defined spec nicely and also helps to avoid interop problem later on.

proper scoping needs processing rules. one way or the other (inheriting when nesting or not), the spec has to tell people how it works and they have to implement it accordingly. no processing rules simply means a not well-defined spec. Obviously, my point was that the processing rules we define should not supercede the basic processing rules of JSON.

JSON has so little "processing" that there's little to worry about.

In other words, the wording shoudl explicitly state that changing the name of the curie represents a breaking change regardless of if the expanded URL remains the same. i.e. "foo:bar" != "baz:bar" even if foo == baz

now i am really confused. that last example to me is violating the spec as i would read it now, and as i hope it will keep defining things. if these two things are not the same, why not, and what exactly is the difference between them? they resolve to the same link relation URI, so what's the difference and how and where does it matter?

even if you tried to make this a reality, i have no idea how that should work. would you tell HAL creators that once they have used a prefix they can never change it again? how could that be enforced, and within which scope? if i get a HAL with prefixes and before i submit it to the corporate repo i change all of them because that's what i like doing, (a) nobody will notice because there's no visible effect outside the HAL source, and (b) it's fine that nobody notices because i haven't changed anything that matters. it's like adjusting indentation.

[mikekelly]

On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde notifications@github.com wrote:

In other words, the wording shoudl explicitly state that changing the name of the curie represents a breaking change regardless of if the expanded URL remains the same. i.e. "foo:bar" != "baz:bar" even if foo == baz

now i am really confused. that last example to me is violating the spec as i would read it now, and as i hope it will keep defining things. if these two things are not the same, why not, and what exactly is the difference between them? they resolve to the same link relation URI, so what's the difference and how and where does it matter?

If I write a client that has code like this:

traverse(resource._links["foo:bar"])

and you rename "foo:bar" to "baz:bar" - you just broke my client.

even if you tried to make this a reality, i have no idea how that should work. would you tell HAL creators that once they have used a prefix they can never change it again?

Yes - this is just normal JSON stuff i.e. if you rename a property, that's a breaking change.

how could that be enforced, and within which scope

as discussed, the easiest way to do scoping is per resource so I'm not sure I see the issue?

if i get a HAL with prefixes and before i submit it to the corporate repo i change all of them because that's what i like doing, (a) nobody will notice because there's no visible effect outside the HAL source, and (b) it's fine that nobody notices because i haven't changed anything that matters. it's like adjusting indentation.

Don't get it. This never happens in JSON APIs, why would it happen with a HAL representation?

Obviously it would be better if if were possible to change the prefix name and the processing rules supported it so that it wasn't a breaking change but I'm not convinced that:

1. It's practically that valueable and/or worth the additional complexity
2. Clients would read the spec and not write stupid code that just treats the qname as an opaque string.

[dret]

On 2017-03-28 22:15, Mike Kelly wrote:

On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde notifications@github.com wrote:

now i am really confused. that last example to me is violating the spec as i would read it now, and as i hope it will keep defining things. if these two things are not the same, why not, and what exactly is the difference between them? they resolve to the same link relation URI, so what's the difference and how and where does it matter?

If I write a client that has code like this:

traverse(resource._links["foo:bar"])

and you rename "foo:bar" to "baz:bar" - you just broke my client.

why would you ever write such a client (assuming it then naively checks for this literal value)? "foo:bar" is not a valid link relation value per RFC 5988, so your client is broken by definition.

a reasonable HAL document would declare the prefix "foo" and your code would look like this (or effectively do it like this by doing CURIE expansion internally):

traverse(resource._links["http/example.org/bar"])

the current HAL spec tells me explicitly that CURIEs are internal to HAL and just used for shorter URI notation within HAL. so anybody not expanding them (a) is writing broken code per HAL, and (b) is writing broken code per RFC 5988.

frankly, i don't think you can have it both ways. use CURIEs and use them consistently and with a well-defined processing model, or don't. trying to say "we're sort of using them but when people ignore them we still hope everything works out well" just means you have a spec with holes and non-interop across implementations.

[mikekelly]

On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde notifications@github.com wrote:

On 2017-03-28 22:15, Mike Kelly wrote:

On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde notifications@github.com wrote:

now i am really confused. that last example to me is violating the spec as i would read it now, and as i hope it will keep defining things. if these two things are not the same, why not, and what exactly is the difference between them? they resolve to the same link relation URI, so what's the difference and how and where does it matter?

If I write a client that has code like this:

traverse(resource._links["foo:bar"])

and you rename "foo:bar" to "baz:bar" - you just broke my client.

why would you ever write such a client (assuming it then naively checks for this literal value)? "foo:bar" is not a valid link relation value per RFC 5988, so your client is broken by definition.

Clients like this get written all the time. People don't read specs, the barely even read API documentation. In a large API with thousands of clients you have no visibility on which clients are naive and which are not, so it's easier to just adopt processing rules which don't trip up "dumb" clients.

a reasonable HAL document would declare the prefix "foo" and your code would look like this (or effectively do it like this by doing CURIE expansion internally):

traverse(resource._links["http/example.org/bar"])

I realise it's possible to try and define the spec to make this possible but, as I said earlier - I don't think it's worth it.

the current HAL spec tells me explicitly that CURIEs are internal to HAL and just used for shorter URI notation within HAL. so anybody not expanding them (a) is writing broken code per HAL, and (b) is writing broken code per RFC 5988.

I don't think 5988 constrains clients, and even if it did this isn't the end of the world.

I think (a) is quite a stretch from the existing wording

frankly, i don't think you can have it both ways. use CURIEs and use them consistently and with a well-defined processing model, or don't. trying to say "we're sort of using them but when people ignore them we still hope everything works out well" just means you have a spec with holes and non-interop across implementations.

Yes, I should not have used "curies" I should have called them "rel doc templates" or something else. I don't want this mechanism to have an impact at run time, it's designed for "design time" so that we can have disocverable link relation documentation but without horribly long keys in our _links objects.

[dret]

On 2017-03-28 23:43, Mike Kelly wrote:

On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde notifications@github.com wrote:

a reasonable HAL document would declare the prefix "foo" and your code would look like this (or effectively do it like this by doing CURIE expansion internally):

traverse(resource._links["http/example.org/bar"])

I realise it's possible to try and define the spec to make this possible but, as I said earlier - I don't think it's worth it.

so i guess i have trouble understanding if/what you think should be done. i guess we agree that the current spec is not well-defined. there are various ways to make it well-defined. these have different results in terms of how they impact current implementations. it is impossible to reconcile everything after-the-fact, so the options are:

• leave the spec ill-defined. even then it would be good to at least add some guidance on what future implementations should do.

• version the spec so that the current ecosystem is untouched. define the new one so that implementations always interoperate.

• make the spec well-defined and decide which implementations will get into trouble. add some language that acknowledges the fix and tells implementers that they might see unexpected things (such as link relation values with colons).

[mikekelly]

This comes up every once in a while. HAL links and RFC 5988 links have an almost 1:1 correspondence. As far as I know, the way they handle CURIEs for relation types is the only exception, which is probably why it grates so much. From the RFC: "When extension relation types are compared, they MUST be compared as strings (after converting to URIs if serialised in a different format, such as a Curie [W3C.CR-curie-20090116]) [...]."

On the other hand, saving clients some post-processing is valuable too. It's Mike's draft, so he wins. :-)

See also this discussion: https://groups.google.com/d/topic/hal-discuss/p59KtwXnu78/discussion

@Mike: I think in the long run removing the term "CURIEs" from the RFC will save you discussion time. And we're due another update anyway since it has expired. :-)

Best, Joost

2017-03-28 17:43 GMT+02:00 Mike Kelly mikekelly321@gmail.com:

On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde notifications@github.com wrote:

On 2017-03-28 22:15, Mike Kelly wrote:

On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde notifications@github.com wrote:

now i am really confused. that last example to me is violating the spec as i would read it now, and as i hope it will keep defining things. if these two things are not the same, why not, and what exactly is the difference between them? they resolve to the same link relation URI, so what's the difference and how and where does it matter?

If I write a client that has code like this:

traverse(resource._links["foo:bar"])

and you rename "foo:bar" to "baz:bar" - you just broke my client.

why would you ever write such a client (assuming it then naively checks for this literal value)? "foo:bar" is not a valid link relation value per RFC 5988, so your client is broken by definition.

Clients like this get written all the time. People don't read specs, the barely even read API documentation. In a large API with thousands of clients you have no visibility on which clients are naive and which are not, so it's easier to just adopt processing rules which don't trip up "dumb" clients.

a reasonable HAL document would declare the prefix "foo" and your code would look like this (or effectively do it like this by doing CURIE expansion internally):

traverse(resource._links["http/example.org/bar"])

I realise it's possible to try and define the spec to make this possible but, as I said earlier - I don't think it's worth it.

the current HAL spec tells me explicitly that CURIEs are internal to HAL and just used for shorter URI notation within HAL. so anybody not expanding them (a) is writing broken code per HAL, and (b) is writing broken code per RFC 5988.

I don't think 5988 constrains clients, and even if it did this isn't the end of the world.

I think (a) is quite a stretch from the existing wording

frankly, i don't think you can have it both ways. use CURIEs and use them consistently and with a well-defined processing model, or don't. trying to say "we're sort of using them but when people ignore them we still hope everything works out well" just means you have a spec with holes and non-interop across implementations.

Yes, I should not have used "curies" I should have called them "rel doc templates" or something else. I don't want this mechanism to have an impact at run time, it's designed for "design time" so that we can have disocverable link relation documentation but without horribly long keys in our _links objects.

-- You received this message because you are subscribed to the Google Groups "HAL Discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss+unsubscribe@googlegroups.com. For more options, visit https://groups.google.com/d/optout.

-- Joost Cassee +31 (0)6 14585693 https://jcassee.com

[mikekelly]

On Thu, Mar 30, 2017 at 10:43 AM, Joost Cassee joost@cassee.net wrote:

This comes up every once in a while. HAL links and RFC 5988 links have an almost 1:1 correspondence. As far as I know, the way they handle CURIEs for relation types is the only exception, which is probably why it grates so much. From the RFC: "When extension relation types are compared, they MUST be compared as strings (after converting to URIs if serialised in a different format, such as a Curie [W3C.CR-curie-20090116]) [...]."

On the other hand, saving clients some post-processing is valuable too. It's Mike's draft, so he wins. :-)

See also this discussion: https://groups.google.com/d/topic/hal- discuss/p59KtwXnu78/discussion

@Mike: I think in the long run removing the term "CURIEs" from the RFC will save you discussion time. And we're due another update anyway since it has expired. :-)

The problem with changing "curies" is that it's a breaking change. One option is remove the reference and define our own curie mechanism in the spec.

[mikekelly]

2017-03-30 11:51 GMT+02:00 Mike Kelly mikekelly321@gmail.com:

The problem with changing "curies" is that it's a breaking change. One option is remove the reference and define our own curie mechanism in the spec.

Yes, I meant just changing the wording, not the working, of the spec.

Best, Joost

-- Joost Cassee +31 (0)6 14585693 https://jcassee.com

[dret]

On 2017-03-30 19:43, Mike Kelly wrote:

2017-03-30 11:51 GMT+02:00 Mike Kelly mikekelly321@gmail.com: Yes, I meant just changing the wording, not the working, of the spec.

the problem with that approach is that it's not the wording of the spec that is broken, but the working.

the fundamental question is where this draft is supposed to go? if the intention is to turn it into a spec, it should be well-defined in the things it is specifying.

[dret]

On 2017-03-30 17:43, Mike Kelly wrote:

On the other hand, saving clients some post-processing is valuable too.

not if that means that interop is broken if two HAL representations happen to choose different prefixes for the same URI.

It's Mike's draft, so he wins. :-)

yes. if it should become a spec, that's a different story.

@Mike: I think in the long run removing the term "CURIEs" from the RFC will save you discussion time. And we're due another update anyway since it has expired. :-)

as mentioned in my previous response, that really doesn't help at all. the problem isn't that those things are called CURIEs. the problem is that the spec is not well-defined in how those things are handled.

[mikekelly]

On Thu, Mar 30, 2017 at 3:18 PM, Erik Wilde notifications@github.com wrote:

On 2017-03-30 19:43, Mike Kelly wrote:

2017-03-30 11:51 GMT+02:00 Mike Kelly mikekelly321@gmail.com: Yes, I meant just changing the wording, not the working, of the spec.

the problem with that approach is that it's not the wording of the spec that is broken, but the working.

the fundamental question is where this draft is supposed to go? if the intention is to turn it into a spec, it should be well-defined in the things it is specifying.

I'm going to optimise the design and semantics for the majority of users, not to satisfy speclords and pedants.

If that means I end up with a specification that can't become an RFC then so be it... it doesn't seem to have been a problem so far anyway.