Define aux & meta in terms of representations

[termontwouter]

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

This PR updates #153 to address 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 another -- 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