CURIE names for link relations #33
Comments
|
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 ***@***.***> 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
<#33>, or mute the
thread
<https://github.com/notifications/unsubscribe-auth/AADZ5mhIBZI8RDfqMpzNExNZfiPo0DR-ks5rpk9QgaJpZM4MpZqm>
.
|
|
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.
|
|
On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde <[email protected]>
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
|
|
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 ***@***.***> wrote:
On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde ***@***.***>
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 ***@***.***
For more options, visit https://groups.google.com/d/optout.
|
|
The challenge with that processing model is we then have to deal with precedence and the complexity goes up.
…Sent from my phone
________________________________
From: [email protected] <[email protected]> on behalf of Andrew Kuklewicz <[email protected]>
Sent: Tuesday, March 28, 2017 2:27:42 AM
To: [email protected]
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 ***@***.***> wrote:
On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde ***@***.***>
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 ***@***.***
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 [email protected].
For more options, visit https://groups.google.com/d/optout.
|
|
On Mar 28, 2017, at 18:43, Mike Kelly ***@***.***> 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.
|
|
On Mar 28, 2017, at 04:00, Mike Kelly ***@***.***> wrote:
On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde ***@***.***>
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.
|
|
On Tue, Mar 28, 2017 at 1:59 PM, Erik Wilde <[email protected]>
wrote:
On Mar 28, 2017, at 04:00, Mike Kelly ***@***.***> wrote:
> On Mon, Mar 27, 2017 at 11:54 AM, Erik Wilde ***@***.***>
> 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
|
|
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.
|
|
On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde ***@***.***> 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.
|
|
On 2017-03-28 22:15, Mike Kelly wrote:
On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde ***@***.***>
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.
|
|
On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde <[email protected]>
wrote:
On 2017-03-28 22:15, Mike Kelly wrote:
> On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde ***@***.***>
> 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.
|
|
On 2017-03-28 23:43, Mike Kelly wrote:
On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde ***@***.***>
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).
|
|
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 <[email protected]>:
…
On Tue, Mar 28, 2017 at 3:53 PM, Erik Wilde ***@***.***>
wrote:
> On 2017-03-28 22:15, Mike Kelly wrote:
> > On Tue, Mar 28, 2017 at 2:53 PM, Erik Wilde ***@***.***>
> > 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 ***@***.***
For more options, visit https://groups.google.com/d/optout.
--
Joost Cassee
+31 (0)6 14585693
https://jcassee.com
|
|
On Thu, Mar 30, 2017 at 10:43 AM, Joost Cassee ***@***.***> 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.
|
|
2017-03-30 11:51 GMT+02:00 Mike Kelly <[email protected]>:
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
|
|
On 2017-03-30 19:43, Mike Kelly wrote:
2017-03-30 11:51 GMT+02:00 Mike Kelly ***@***.***>:
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.
|
|
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.
|
|
On Thu, Mar 30, 2017 at 3:18 PM, Erik Wilde <[email protected]>
wrote:
On 2017-03-30 19:43, Mike Kelly wrote:
> 2017-03-30 11:51 GMT+02:00 Mike Kelly ***@***.***>:
> 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.
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
The text was updated successfully, but these errors were encountered: