Define Storage Description Resources as a specialization of CID-1.0

[acoburn]

This defines the Storage Description resource as a specialization of a Controlled Identifier Document (CID 1.0). There are three notable changes:

• The canonical representation of a Storage Description Resource now uses the application/lws+cid media type.
• The serialization of a Storage Description Resource requires the following URIs in the @context property:
  • https://www.w3.org/ns/cid/v1
  • https://www.w3.org/ns/lws/v1
• Several terms in the LWS vocabulary that had previously been copied from the CID context are no longer necessary to define in the LWS context

Otherwise, the basic shape of the JSON serialization of a Storage Description Resource remains the same.

---

Preview | Diff

[acoburn]

There are a few tensions between the current definition of an LWS Storage Description resource and a CID 1.0 document. These tensions are not unresolvable, but it would be good to have some feedback from the group.

The current state of this PR describes the storage description like so:

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "service": [{
    "type": "StorageDescription",
    "serviceEndpoint": "https://storage.example/description"
  }]
}

This formulation is problematic due to the CID requirements on the id field. In short, in order for this to work with CID, this resource needs to be dereferenced at the https://storage.example/ URL, not https://storage.example/description.

One option I considered was to co-locate the storage description resource at the storage root, relying on content negotiation to modulate between different representations (application/lws+cid vs. application/lws+json). This, however, has the significant downside that access control rules for a storage description is typically very different than the access control rules for a storage root. While this may work for some deployments/implementations, I find it problematic in the general case.

That leaves two main alternatives:

1. When a client dereferences the storage URI, the server responds with the storage description. The subject of the document is the storage and includes a pointer to the storage root. This doesn't prohibit the storage root and storage description from being co-located at the same storage URL, though I imagine that they will often be identified with different URLs. This also means that the link headers used elsewhere could be simplified from Link: <...>; rel=storageDescription to Link: <...>; rel=storage. In this example, the term root is a placeholder:

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/",
  "type": "Storage",
  "root": "https://storage.example/root/",
  "service": [{
    ...
  }]
}

2. Keep the storage-description-as-CID distinct from the storage. This involves a potentially simpler integration with CID documents but the subject of the document becomes the storage description, not the storage. In this model, the storage property could also be moved into a service block with type=Storage and serviceEndpoint=https://storage.example/.

{
  "@context": [
    "https://www.w3.org/ns/cid/v1",
    "https://www.w3.org/ns/lws/v1"
  ],
  "id": "https://storage.example/description",
  "type": "StorageDescription",
  "storage": "https://storage.example/",
  "service": [{
    ...
  }]
}

In the early discussions of this topic (LWS Meeting 2025-12-15), there was general consensus on having the subject of this document be the storage. Option 1 is in line with that consensus while option 2 is not.

[pchampin]

@acoburn I totally agree with your analysis above. And I don't like option2, precisely for the reason you outline in the end.

The spec currently says (emphasis is mine):

The URI for a storage description can be distinct from the URI identifying a storage, which can be distinct from the storage root. These URIs can also be identical, provided that the resulting representation conforms to the requirements outlined in this document.

If we want to make the storage description a compliant CID, then the URI identifying the storage and the URI identifying the root could not be identical. In fact the URI identifying the storage could not even dereference (even indirectly, via fragment removal or 303 redirect) to the storage root, because it is required (for the CID to be valid) to dereference to the storage description.
(that is, unless we accept the content negotiation hack that you describe above, but I concur with you that it has a strong smell)

I could live with that, but it is unfortunate. It creates an incompatibility with Solid:

The storage resource (pim:Storage) is the root container for all of its contained resources (see Resource Containment).

Maybe we are better of reusing the CID vocabulary (and potentially even the CID context), but not claiming CID compliance for the Storage Description :-/ As @dmitrizagidulin pointed out during the last WG call, CID compliance is important if we were to verify signatures (or other proof) issued by the storage; I don't think we have use-cases for that... We are merely reusing the vocabulary used in CID documents...

[elf-pavlik]

As @dmitrizagidulin pointed out during the last WG call, CID compliance is important if we were to verify signatures (or other proof) issued by the storage; I don't think we have use-cases for that... We are merely reusing the vocabulary used in CID documents...

well, we currently have:

https://w3c.github.io/lws-protocol/lws10-notifications/#signature-verification

[...]

• Dereference the storage identifier to retrieve the storage description resource. The id property of the top-level document map MUST match the storage identifier.
• Find the object in the verificationMethod array whose id property matches either the full keyid URL or the fragment component of the keyid URL.