Linkset URI (not resource)

[gibsonf1]

lws-protocol/lws10-core/Operations/update-resource.md

Line 38 in d8a4de3

A resource's metadata is updated by modifying its corresponding linkset resource, discovered via the Link header with rel="linkset".

"A resource's metadata is updated by modifying its corresponding linkset URI ..." (not linkset Resource)

Where that linkset resource on server may be part of the main data resource it references (not a separate implementation resource), with the linkset simply referencing a part of the total resource using a query string (The TwinPod case) such that a GET request to the main URI returns the full data for that resource (including the linkset part)

[pchampin]

I'm confused, because I don't see how the change you propose ("resource" → "URI") is related to the concern you express in your comment.

• "modifying the corresponding linkset resource" (current text) means PUTting new metadata to the URI that is the value of Link rel="linkset"
• "modifying the corresponding linkset URI" (your proposal) would mean changing the URI that is the value of the Link rel="linkset" -- to a different URI, that would still be a different URI from the resource about which the metadata is, thus contradicting your desire to keep "the full data for that resource (including the linkset part)" inside the resource itself.

Note also that keeping the linkset inside the resource itself is not possible for all kinds of resources... In general, we want to allow for LWS data resources to contain images, plain text... which requires metadata to be hold separately.

Even when a data resource contains RDF triples, keeping some metadata out of it (especially the server-managed metadata, e.g. the link to the ACL auxiliary resource).

[gibsonf1]

I'm confused, because I don't see how the change you propose ("resource" → "URI") is related to the concern you express in your comment.

• "modifying the corresponding linkset resource" (current text) means PUTting new metadata to the URI that is the value of Link rel="linkset"
• "modifying the corresponding linkset URI" (your proposal) would mean changing the URI that is the value of the Link rel="linkset" -- to a different URI, that would still be a different URI from the resource about which the metadata is, thus contradicting your desire to keep "the full data for that resource (including the linkset part)" inside the resource itself.

Note also that keeping the linkset inside the resource itself is not possible for all kinds of resources... In general, we want to allow for LWS data resources to contain images, plain text... which requires metadata to be hold separately.

Even when a data resource contains RDF triples, keeping some metadata out of it (especially the server-managed metadata, e.g. the link to the ACL auxiliary resource).

I am not proposing anything but to refer to the the linkset as a representation, rather than a resource in itself. So I'm not proposing any change to the PUT etc, just to referring to the Linkset as a "representation" rather than a "resource" for those implementations that are data first such that the linkset is literally a representation from the complete resource at the same URI (where perhaps for the data first implementation case, the URI would be appended with a query string to indicate the linkset representation is needed or via accept.

[acoburn]

Definitions are helpful, and these definitions come from RFC 9110 HTTP Semantics

Resources: The target of an HTTP request is called a "resource".

Representations: A "representation" is information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol.

In the context of linksets, the defined API for referring to and interacting with linksets over HTTP is via link headers:

Link: <linkset-resource>; rel="linkset"

The target of the link header (i.e. linkset-resource) is a resource identified with a URI.

When one dereferences the resource at that URI, you now are in the realm of representations, and RFC9264 defines two standard representations of the linkset resource. LWS requires support for the application/linkset+json format, and a server may offer different representations, if it so chooses.

Furthermore, LWS requires that the resource identified via the linkset link relation also support the PATCH method with application/merge-patch+json bodies.

The LWS terminology section defines linkset as "[a] separate resource associated with each LWS resource", which indicates that the LWS resource and linkset resources are distinct. And please note that https://example.com/resource and https://example.com/resource?linkset are two distinct resources.

The main reason to keep the linkset resource separate from the associated LWS resource is to allow for specialized operations that may not apply to an LWS DataResource or Container, particularly PATCH with application/merge-patch+json. For example, if the DataResource and linkset are the same resource, a PATCH operation with application/merge-patch+json would be ambiguous: would it apply to the linkset or to the data in the DataResource? Or both? Either way, that will introduce ambiguity for clients, which is precisely what we should avoid in a specification.

[gibsonf1]

Definitely agree with the definitions, especially this part "HTTP does not limit the nature of a resource; it merely defines an interface that might be used to interact with resources." So HTTP is about interfacing with resources via specified represenations of those resources without saying anything about the nature of the underlying resource.

The target of the link header (i.e. linkset-resource) is a resource identified with a URI.

The spec is about the Representation of the linkset from a resource without saying anything about the nature of that resource per HTTP definition. In the case a data-first implementation like TwinPod, we would never create an additional data resource about a data resource, it would make no sense at all. The linkset would be a representation from the same resource that the linkset is about.

Furthermore, LWS requires that the resource identified via the linkset link relation also support the PATCH method with application/merge-patch+json bodies.

In the data-first implementation scenario, if server recieves a PATCH on a linkset URI (likely easiest by indicating that representation is desired using a query string) server would then make a change as requested to the single underlying resource that the linkset representation is a part of.

The LWS terminology section defines linkset as "[a] separate resource associated with each LWS resource", which indicates that the LWS resource and linkset resources are distinct. And please note that https://example.com/resource and https://example.com/resource?linkset are two distinct resources.

Clearly, this is what needs to be revised as LWS should not be making any requirements about the nature of implementation resources per HTTP spec. As I've noted above, for a data-first implementation, it would make no sense at all to make a data resource about the same data resource.

The main reason to keep the linkset resource separate from the associated LWS resource is to allow for specialized operations that may not apply to an LWS DataResource or Container, particularly PATCH with application/merge-patch+json. For example, if the DataResource and linkset are the same resource, a PATCH operation with application/merge-patch+json would be ambiguous: would it apply to the linkset or to the data in the DataResource? Or both? Either way, that will introduce ambiguity for clients, which is precisely what we should avoid in a specification.

Again, the main reason you state above is taking a specific implementation's limitations into mind. These requirements can be easily fulfilled by a data-first implementation having a single primary resource where the linkset is just a representation of that resource and serves to indicate to the server what the user requires changing, etc.

It makes no sense at all for LWS to depart from HTTP and start making requirements about the nature of underlying resources.

[acoburn]

In the data-first implementation scenario, if server recieves a PATCH on a linkset URI (likely easiest by indicating that representation is desired using a query string) server would then make a change as requested to the single underlying resource that the linkset representation is a part of.

This has already been mentioned multiple times in this and other threads: if you add a query string to a URL, you are now identifying a different resource.

That is https://example.com/ and https://example.com/?foo are different resources.

And so even in the example you provide, you are relying on the existence of separate resources: one for your data resource and a separate one for the linkset resource.

[gibsonf1]

This has already been mentioned multiple times in this and other threads: if you add a query string to a URL, you are now identifying a different resource.

Do you have a spec reference for this point? It would not seem consistent with the idea that HTTP is about interfacing to resources without saying anything about the nature of them. And the URI is about addressing, not defining a resource?

[acoburn]

I would highly recommend familiarizing yourself with the entire URI specification.

https://datatracker.ietf.org/doc/html/rfc3986

[gibsonf1]

I would highly recommend familiarizing yourself with the entire URI specification.

https://datatracker.ietf.org/doc/html/rfc3986

Thanks, I am quite familiar with that spec. I can't find where it specifies that any character difference in a URI means that the resource on a server is now a different one?

For example, in the case of query: https://datatracker.ietf.org/doc/html/rfc3986#section-3.4

The query component contains non-hierarchical data that, along with
   data in the path component ([Section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)), serves to identify a
   resource within the scope of the URI's scheme and naming authority
   (if any).  The query component is indicated by the first question
   mark ("?") character and terminated by a number sign ("#") character
   or by the end of the URI.
      query       = *( pchar / "/" / "?" )

   The characters slash ("/") and question mark ("?") may represent data
   within the query component.  Beware that some older, erroneous
   implementations may not handle such data correctly when it is used as
   the base URI for relative references ([Section 5.1](https://datatracker.ietf.org/doc/html/rfc3986#section-5.1)), apparently
   because they fail to distinguish query data from path data when
   looking for hierarchical separators.  However, as query components
   are often used to carry identifying information in the form of
   "key=value" pairs and one frequently used value is a reference to
   another URI, it is sometimes better for usability to avoid percent-
   encoding those characters.

Are you saying that any use of a query on a URI means that the server is offering up some completely different resource, such as with paging etc? This does not seem to be the intent of the spec in any way.

[elf-pavlik]

Technically different URIs could still identify the same resource
https://www.w3.org/TR/webarch/#future-comparison

Without OWL I don't know if there's a way to assert that multiple URIs identify the same resource. Even something like rel="canonical" to my knowledge doesn't entail it. Maybe @CxRes has more insights on IETF position on that.

Either way, if URIs just differ by a query, I don't think one can make any assumptions if denoted resources are different or the same.

"A resource's metadata is updated by modifying its corresponding linkset URI ..." (not linkset Resource)

@gibsonf1 could you pleaes illustrate it with few snippets?

[gibsonf1]

Example URI denoting same resource:
https://lws.twinpod.us/node/t_a3?start=0&limit=20
https://lws.twinpod.us/node/t_a3?representation=linkset

[elf-pavlik]

Example URI denoting same resource:

How would a client draw such conclusion?

[gibsonf1]

Example URI denoting same resource:

How would a client draw such conclusion?

Not sure what you mean, it is the client to specify to the server the specifics it wants about the resource on the server, such as specific paging, or a specific kind of representaton for it like meta or linkset etc. The URI with query in this example would be in the headers, so the app would just use it. This is my point, we are specifying representations with the LWS spec, not the nature of the underlying resources on the server.

[elf-pavlik]

A resource's metadata is updated by modifying its corresponding linkset resource, discovered via the Link header with rel="linkset".

Actually this sentence doesn't seem to prevent a resource and its corresponding linkset resource to be considered as the same resoure by your implementation.

The LWS terminology section defines linkset as "[a] separate resource associated with each LWS resource", which indicates that the LWS resource and linkset resources are distinct.

Since HTTP doesn't seem to define if resource identified by different URIs is different or the same maybe LWS also doesn't need it to be strongly defined. I guess owl:differentFrom would need to be asserted to exclude possibility of them being the same resource.

[laurensdeb]

@gibsonf1 Thank you for raising this issue. While the concern you raise deserves further consideration, I don't see how the proposed wording would resolve the underlying ambiguity, swapping "resource" for "URI" still leaves open what exactly is being modified.

I think this is closely related to #67, where @damooo proposed generalising the notion of auxiliary resources to unify the lifecycle of linksets, ACLs, and similar supplementary resources, rather than handling each in an ad-hoc way. We could consider a linkset to be an auxiliary resource in that sense, and I suspect addressing the terminology through #67 would give us a more principled vocabulary than a one-word edit here.

The TwinPod pattern you describe, where the linkset is a view onto the primary resource, is interesting, but it raises questions the current text sidesteps: How is the linkset updated if it has no independent write endpoint? What does that imply for the resource itself? Does modifying the primary resource implicitly modify the linkset? How do conditional requests and ETags behave?

I'm not opposed to changing the language, but I'd rather we decide first whether embedded linksets are conformant, and then pick wording that reflects that decision.

Is my understanding of your concerns correct? Or am I missing certain details here?