Define aux & meta in terms of representations

[termontwouter]

Resolves #67, #125, #127, #147
Supersedes #113

Following up on #153, this proposal addresses the tension around auxiliary/metadata resources. In short, it redefines the must-haves in terms of representations, on top of which the (optional) resource variant is then defined.

Definitions

For clarity, here are the adapted definitions in a logical order.

• metadata representation: a representation of an LWS resource, that provides additional information describing the resource.

• linkset representation: a metadata representation containing the linkset of an LWS resource, conforming to RFC9264. The metadata resource exposing this representation is called the linkset document of the primary resource. Updates of linkset representations follow the requirements outlined in Section 9. Operations.

• metadata resource: an auxiliary resource that exposes a specific metadata representation of its primary resource, and conforms to the conventions described in ...

• auxiliary resource: an LWS resource whose lifecycle is bound to a non-auxiliary LWS resource, called its primary resource. One type of auxiliary resources are metadata resources, as defined in this specification, but LWS Servers are free to manage additional kinds of auxiliary resources (e.g., access control resources, notification inboxes).

Conformance

Since we agreed to keep the terminology high-level, I've left out a number of important details, which I summarize here to take up in one or more future PRs.

• Linksets are unique per primary resource.
• The linkset representation can be requested through content negotiation for application/linkset+json.
• Linksets can be modified by clients to manage their primary resource's relationships, except for certain protected link types specified by the server.
• Auxiliary resources (if any) are not contained in a container hierarchy.
  • However, LWS servers are free to list them as part of their primary resource's contained resource description.
• The URI of an auxiliary resource (if any) is discoverable from its primary resource via Link headers of the appropriate relation type.
• The URI of an metadata resource (if any) is declared in the Content-Location header field in response to content-negotiated requests for its corresponding metadata representation targeting its primary resource's URI

For anyone who is less familiar with that header, here's an excerpt from RFC 9110 (HTTP Semantics):

The "Content-Location" header field references a URI that can be used as an identifier for a specific resource corresponding to the representation in this message's content ... For a response to a GET or HEAD request, this is an indication that the target URI refers to a resource that is subject to content negotiation and the Content-Location field value is a more specific identifier for the selected representation.

Additional suggestions

• Require the use of the linkset type parameter.
• Specify the containment representation of a container as a type of metadata representation.
• Treat the conformance w.r.t. metadata uniformly across LWS resource types (so also for non-RDF resources).
  • This separates server- vs. client-managed metadata more clearly.
  • It also diminishes the 'special role' of RDF; e.g., servers could provide non-RDF metadata representations for RDF resources).
• Define a specific metadata representation containing all server-managed metadata of a resource.
  • This representation can be read-only, so can be (profiled) JSON-LD, including not only the linkset as triples but also literal metadata.
• Specify a client-managed link relation type (e.g., rel="describedby") that turns a resource into a metadata resource for another (primary) resource.
  • Their lifecycle is then managed by the server in accordance with its primary resource.

---

Preview | Diff

[acoburn]

Thanks @termontwouter, I like the direction this is going. The additional suggestions section is also interesting; the suggestion about allowing a client to change an LWS resource into a metadata resource (and vice-versa) is something we would want to think carefully about.

[gibsonf1]

allowing a client to change an LWS resource into a metadata resource (and vice-versa) is something we would want to think carefully about.

I think the idea that LWS as a spec says things about the nature of resources on servers is not a good approach. There will be implementations, such as ours, where its all the same resource with various representations. The spec should clearly not make the nature of implementation resource claims such that they are separate, the same, etc as that is up to the implementation.

[termontwouter]

@gibsonf1

I think the idea that LWS as a spec says things about the nature of resources on servers is not a good approach. There will be implementations, such as ours, where its all the same resource with various representations. The spec should clearly not make the nature of implementation resource claims such that they are separate, the same, etc as that is up to the implementation.

I fully agree, and that is the entire point of this PR: to redefine the core requirements (MUSTs) in terms of representations rather than resources.

Everything else that still mentions resources (definitions part of this PR, and suggestions in the comment) is optional functionality (MAYs) that a server can provide, and is defined on top of the representations (i.e., syntactic sugar, as it were).

[pchampin]

I think the idea that LWS as a spec says things about the nature of resources on servers is not a good approach.

@gibsonf1 please stop bringing up that strawman argument. When we define a protocol, we are not specifying the "nature" of anything, only a behaviour (i.e. what can be seen from the other end of the protocol). And yes, we are specifying the behaviour of resources, i.e. the thing you interact with via a Uniform Resource Identifier. A resource is the recipient of a GET or a POST query, and responds with a representation of itself.
I'm not inventing anything or pushing for an opinion here; this is what Fielding's thesis, the TAG's Web Architecture, and the HTTP specification describe.

This frustration aside, I'm not against this PR (althouh I'm a bit concerned that the additional genericity will make interoperability harder).

[w3cbot]

This was discussed during the #lws meeting on 01 June 2026.

View the transcript

Auxiliary/Metadata resources discussion #165

<pchampin> w3c/lws-protocol#165

termontwouter: PR itself only does what it says in the first section
… it rewrites few of the terminology that we have, so it is clearer that there doesn't need to be a specific resource that handles metadate etc.
… metadata representation ????, also the linkset
… we can have linkset as separate resource, but that would be defined on top of the representation aspect

<TallTed> w3c/lws-protocol#165

<gb> Pull Request 165 Define aux & meta in terms of representations (by termontwouter)

termontwouter: in conformance section i propose that we take the representation as MUST and leave the resource as MAY
… server can choose what it provides

pchampin: to make sure that i understand the consequences of this PR
… currently to get the linkset of a given LWS resource i discover it by a link in the headers of the resource
… would there be a different way to get the linkset or no specified way to get the linkset

termontwouter: the main way is to get it partially via the link headers
… when we talk about reprentation of the linkset, it would change to the content negotiation on the resource itself
… optionally with the link header that is separate from the resource itself

<Zakim> elf-pavlik, you wanted to ask about test suite

elf-pavlik: it would be interesting to discuss with Samu how this could be implemented
… it would make it harder to discuss this
… a practical way would be to write a test for it

<pchampin> one issue that I see with this approach is that a LWS resource could not have application/linkset as its "main" media type

gibsonf1: on elf-pavlik point of implementation, this is how our implementation currently works
… we can test agains it

termontwouter: can you give a pointer to that in PR?

<Zakim> acoburn, you wanted to ask about interoperability

acoburn: i want to bring up issue of the interop and that we have it foremost in mind

<pchampin> https://www.rfc-editor.org/rfc/rfc9264.html

acoburn: linkset RFC describes discover via the linkset header
… URI could be the same as the primary resource
… one could possibly have a media type listed
… i could see that as a path, we want to be clear about the interop story

termontwouter: i'm not sure how the linkset spec is written about use of header, i can look at it again

acoburn: i would be happy with the direction of this PR if we can ensure the client interop

termontwouter: i'll give some assurance by next week

elf-pavlik: I can think of the link header as an optimisation
… one could try conneg, and fallback to link header if it fails

termontwouter: #116 contains some examples

<gb> Issue 116 Abstract 'containers' as Link Set representations of arbitrary relational metadata (by termontwouter)

acoburn: please take a look at the PR, I would like to vote on it next week, please be prepared

TallTed: incuding links to those PRs in the agenda would be helpful

---

[pchampin]

Following the conversation during today's call: I am uncomfortable with switching the default discovery mechanism of metadata or linkset to content-negotiation. I'm not convinced that the "linkset representation" and "metadata representation" are always "representations" of the primary resource in the sense REST/HTTP uses the term "representation". It describes the primary resource, sure, but does it represent it?

I appreciate this is a rather philosophical debate, which may not be very productive. I also acknowledge that, for some resources in some implementation, forcing a metadata resource to be distinct from the primary resource (as the current text may imply), is not ideal. But the intent of this PR seems to be too much on the other side.

As @acoburn described during the call, discovery via a link (link header, or link in the linkset) allows in principle the link to point to the same resource. So this discovery mechanism provides for both use-cases. What we would need to do is to allow an auxiliary resource to be, in some situation, the same as its primary resource.

I'm submit an alternative PR to this one later today, following this idea.

[termontwouter]

@pchampin

I'm not convinced that the "linkset representation" and "metadata representation" are always "representations" ... It describes the primary resource, sure, but does it represent it?

Anything that describes something surely represents it, since description is a form of representation, no? For example, your GitHub profile displays your GitHub profile picture and states "Pierre-Antoine Champin, Lyon - France, Member of World Wide Web Consortium"; the former depicts you, the latter describes you, both are representations of you.

While this can indeed quickly become philosophical, we can look at the actual HTTP spec (RFC9110), where a representation is defined as "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." To me, this clearly encompasses the information we call a link set.

---

@acoburn

To address the potential issue you raised during last call: the linkset spec (RFC9264) does not require or even recommend it to be discoverable through link header. It states:

A link with the "linkset" relation type MAY be provided in the header field and/or the body of a resource's representation. It may also be discovered by other means, such as through client-side information.

[termontwouter]

As promised in today's meeting, here's an example, highlighting the equivalence with #167. Content and irrelevant headers are omitted for brevity.

Retrieving a Turtle resource

• Request:

  GET /docs/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: text/turtle
  

• Response when link set URI equals resource URI:

  HTTP/1.1 200 OK
  Content-Type: text/turtle
  Link: </docs/1234> ; rel="linkset"
  

• Response when link set URI does not equal resource URI:

  HTTP/1.1 200 OK
  Content-Type: text/turtle
  Link: </links/1234> ; rel="linkset"
  

Retrieving a Link Set

• Request when link set URI equals resource URI:

  GET /docs/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: application/linkset, application/linkset+json
  

• Request when link set URI does not equal resource URI:

  GET /links/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: application/linkset, application/linkset+json
  

• Response when link set URI equals resource URI:

  HTTP/1.1 200 OK
  Content-Type: application/linkset+json
  

• Response when link set URI does not equal resource URI:

  HTTP/1.1 200 OK
  Content-Type: application/linkset+json
  Content-Location: </links/1234>
  

---

Importantly, all the messages above are correct both in PR #165 and in PR #167.

• The only PRACTICAL difference is that in Define aux & meta in terms of representations #165, the client can COUNT on content negotiation for the link set to be possible, which enables LWS-aware clients to skip the link header discovery, while in auxiliary resource as a role #167 that is not the case.
• The only THEORETICAL difference is that in Define aux & meta in terms of representations #165, the fact that a single URI can potentially return both a primary representation and a link set is clarified terminologically by specifying that the link set is in fact a representation of the resource.

[acoburn]

@termontwouter thank you for providing the examples. Would you be able to rebase this PR? There are some conflicts with the recently merged terminology PR

[pchampin]

• The only PRACTICAL difference is that in Define aux & meta in terms of representations #165, the client can COUNT on content negotiation for the link set to be possible, which enables LWS-aware clients to skip the link header discovery, while in auxiliary resource as a role #167 that is not the case.

which leads to an undesirable (IMO) consequence: applications are not free to use application/linkset(+json) for their own data.

Consider the following:

PUT /docs/1234 HTTP/1.1
Host: https://lws.example.org
Content-Type: application/linkset+json

{ "linkset": ... }

Then what do I get when I do

GET /docs/1234 HTTP/1.1
Host: https://lws.example.org
Accept: application/linkset, application/linkset+json

?

The content I just PUT? Or the server-managed links related to /doc/1234?

Granted, my distinction above between "describe" and "represent" might not be the best way to frame the issue. Think of it in terms of "data" (or "state", or "content") vs. "metadata", but that distinction is not always crisp either. I hope my example above makes it clearer what I'm trying to convey.

[elf-pavlik]

which leads to an undesirable (IMO) consequence: applications are not free to use application/linkset(+json) for their own data.

What is the use case to do it? If they just want to store a snippet they can just use application/json.

[acoburn]

which leads to an undesirable (IMO) consequence: applications are not free to use application/linkset(+json) for their own data.

What is the use case to do it? If they just want to store a snippet they can just use application/json.

I would reverse the question: what is the rationale to disallow a particular media type across all implementations?

[elf-pavlik]

I don't think it needs to be disallowed across all implementations. LWS needs to define what can be managed by the client and what has to be managed by the server. Then depending on how servers manage linkset resources/representations they would handle it differently.

I understood example used by @pchampin as client wanting to ceate resource with media type of a linkset but not intending it to act as (have role of) linkset in LWS storage. That's why I wanted to clarify that use case.

[pchampin]

I don't think it needs to be disallowed across all implementations.

I think that's exactly what it does. @woutermont wrote "the client can COUNT on content negotiation for the link set to be possible", which means that servers MUST return the server-managed linkset of a resource whenever someone GETs that resource with Accept: application/linkset (whether or not the server manages it as a separate resource). That effectively turns this media type into a reserved one.

I understood example used by @pchampin as client wanting to ceate resource with media type of a linkset but not intending it to act as (have role of) linkset in LWS storage. That's why I wanted to clarify that use case.

I don't have a clear use-case in mind, TBH, but restricting which media-types clients can use is a bad smell for me.

But let's improvise one: imagine a an app building the "map" of a web-site, consolitading all the "next", "prev", "up" links of all the pages of that website into a single resource. Obviously, the linkset "inside" the resource (client-managed) is disjoint from the linkset "about" the resource (server-managed).

[woutermont]

Thanks for the elaborate clarification, @pchampin. I now see better what causes our disagreement over this:

Obviously, the linkset "inside" the resource (client-managed) is disjoint from the linkset "about" the resource (server-managed).

If I remember correctly, during the meetings in London we decided specifically to use the linkset media types (and not full json-ld) because this would keep it feasible to manage links managed by the client and links managed by the sever within the same representation. In particular, I believe we would let the sever declare a limited set of link types that the client can't modify, while all other links would be under the client's control.

If this is still how we want to approach link sets, your issue with this PR should be resolved. If not, I agree that we may need to revise it.

[pchampin]

If I remember correctly, during the meetings in London we decided specifically to use the linkset media types (and not full json-ld) because this would keep it feasible to manage links managed by the client and links managed by the sever within the same representation.

No, you didn't quite get my point, but that's my fault for using shortcuts. When I wrote "server-managed", I was indeed talking about the "partially server-managed and partially client-managed" linkset that the spec currently calls "linkset resource". I refrained from using the term "linkset resource", because this PR is precisely about banning that term. But it seems that I created more confusion :-(

In my scenario, there are two distinct contents, both (primarily represented) with the linkset media-type:

• the content (state, in REST parlance) of the resource it self, which is entirely client-managed
• the content of what we called "linkset resource", and what you propose to call "linkset representation"; this one is at least partially server-managed, even if the client may add its own links in it

When I do a simple GET on the resource (Accept: *), the body of the response will be the former, and the Link header will contain the latter (in the appropriate format of course). So that should govern the decision of a client to put a link in the former or the latter. The Content of the response would be application/linkset.

With your proposal, doing a GET with Accept: application/linkset would result in something completely different, namely the latter content in the body. That seems wrong.

Worse: if the client now PUTs data with Content-Type: application/linkset, which content should the server alter? The former or the latter??

[termontwouter]

In my scenario, there are two distinct contents, both (primarily represented) with the linkset media-type

I understood that already, so my response does not change, but I'll try to make it clearer as well.

• the content (state, in REST parlance) of the resource it self, which is entirely client-managed
• the content of what we called "linkset resource", and what you propose to call "linkset representation"; this one is at least partially server-managed, even if the client may add its own links in it

As I see it, there is no reason for these contents to be separated. Metadata is already part of the REST state anyway. Suppose we have those two "types of content":

• one contains a number of client-managed links;
• one contains a number of client-managed links, and a number of server-managed links.

Now, why would a client want to distinguish between its managed links? This question seems to lie at the core of our difference in opinion.

When I do a simple GET on the resource (Accept: *), the body of the response will be the former, and the Link header will contain the latter (in the appropriate format of course). So that should govern the decision of a client to put a link in the former or the latter. The Content of the response would be application/linkset.

To me, this makes no sense. If the primary representation has the media type application/linkset, there cannot be another separate application/linkset representation; what would that even mean (webarch-wise)?

With your proposal, doing a GET with Accept: application/linkset would result in something completely different, namely the latter content in the body.

In my proposal, such a resource would simply respond with the same content, both on the Accept: * request and on the Accept: application/linkset one.

If the client now PUTs data with Content-Type: application/linkset, which content should the server alter? The former or the latter??

Again, not an issue in this proposal: it would alter the SINGLE application/linkset representation that the resource consists of (taking into account the server-managed links, which cannot be modified).

[TallTed]

Suggested change

<li><dfn>auxiliary resource</dfn> &mdash; an <a>LWS resource</a> whose lifecycle is bound to a non-auxiliary <a>LWS resource</a>, called its <dfn>primary resource</dfn>. One type of auxiliary resources are <a>metadata resources</a>, as defined in this specification, but <a>LWS Servers</a> are free to manage additional kinds of auxiliary resources (e.g., access control resources, notification inboxes).</li>

<li><dfn>auxiliary resource</dfn> &mdash; an <a>LWS resource</a> whose lifecycle is bound to a non-auxiliary <a>LWS resource</a>, called its <dfn>primary resource</dfn>. One type of auxiliary resource is a <a>metadata resource</a>, as defined in this specification, but <a>LWS Servers</a> are free to manage additional kinds of auxiliary resources (e.g., access control resources, notification inboxes).</li>

[pchampin]

@woutermont

To me, this makes no sense. If the primary representation has the media type application/linkset, there cannot be another separate application/linkset representation; what would that even mean (webarch-wise)?

Because you insist on considering that they "represent" the resource in the same way¹, which is what makes no sense to me.

While I agree that the boundary between data and metadata is sometimes blurry, there are a number of cases where it is crisp enough. For example, files on a filesystem have a clear distinction between their data (the content of the file) and their metadata (name, owner, group, creation and modification date, etc...). Most metadata (dates are an exception) evolve independently from the data, and vice-versa.

In my opinion, the same goes for a Web resource. It has a state (the S in REST), which is serialized in the body of the response to a GET. And it has some additional metadata, some of it is manifested in the headers. The "linkset resource" is a metadata resource, not an alternative representation of the state.

It seems that, on the contrary, you consider that all the information about the resource (data + metadata) constitute its state, and that the body and the link headers are different "projections" of that state (also depending on the media-type of the body). Would you agree with this description of your point of you?

---

¹ Following your logic, the current practice in Solid that separates the ACL from the content of a (Turtle) resource makes no sense either: we have two different representations of the same resource with the same media-type application/turtle.
Otherwise, could you develop what in your view makes the ACL resource more "disjoint" from the primary resource than a linkset resource?

If so, then would you also consider that the ACL of a Turtle resource should also be stored in the resource itself? Following your logic, the current practice in Solid of separating two "representations" of the same resource with the same media-type "text/turtle" makes no sense/.