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.

[termontwouter]

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 most definitely have: server authentication, provenance tracking, integrity checks, legal compliance (auditing) ...

I believe one important conclusion from our face-to-face meeting in London was that storages and storage roots do not need to be the same. Whether Solid currently aligns with that or not should not matter. Option 1 is thus perfectly applicable.

[elf-pavlik]

https://w3c.github.io/lws-protocol/lws10-core/#terminology

storage root — a container at the root of a containment hierarchy of a storage. The storage root is the only LWS resource that does not have a parent in the LWS containment hierarchy nor a primary resource.

https://w3c.github.io/lws-protocol/lws10-core/#container-model

Every LWS storage has a storage root that serves as the top-level organizational unit. The storage root has no parent and acts as the entry point for the storage hierarchy.

Given efforts like @jeswr's

• Proposal: Access-Controlled SPARQL Query over a Solid Pod solid/specification#804

Can the containment tree starting with the root container be a service as well?

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

Since LWS containment has to be explicit and asserted with lws:contains, I think namespace owner has a lot of flexibility in how they allocate URLs. All below should be valid.

{
  "id": "https://storage.example/id",
  "type": "Storage",
  "service": [{
    "type": "RootContainerService",
    "serviceEndpoint": "https://storage.example/"
  }]
}

{
  "id": "https://id.example/storage",
  "type": "Storage",
  "service": [{
    "type": "RootContainerService",
    "serviceEndpoint": "https://storage.example/"
  }]
}

Technically this could still probably allow root to be the same as the storage, but we may need to add a note that implementation doing it may need to have exception for CID content type in their access control mechanism.

[pchampin]

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 most definitely have: server authentication, provenance tracking, integrity checks, legal compliance (auditing) ...

You are right, I stand corrected.

Then this PR seems the best way forward.

I also like @elf-pavlik's suggestion to declare the root container(s) as a special kind of service.

[renyuneyun]

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.

I checked the minutes again, and found some observations of the discussion:

1. Many are fine in either way, but just slightly more inclined towards having the subject of the document being the Storage;
2. There was a concern of Storage Root being different from the storage (for departing from Solid);
3. (My conclusion) People were in the assumption that we can arbitrarily place and arbitrarily define the fields of the Storage Description, and that will not affect how we define or place Storage Root.

Indeed, there is still the choice to make, but it seems to me that the old consensus no longer takes that much priority in this thread, given that CID compliance changes the basic assumptions of the discussion.

---

To me, if there has to be a choice of either restricting the location of Storage Root or restricting the location of Storage Description, I'm more inclined to restrict the second. It makes more sense to allow arbitrary placement of Storage Root than Storage Description, both for flexibility and being intuitive.
(Alas, we need to make something unintuitive anyway, for compliant with CID. Why not Storage Description?)

@elf-pavlik's comments also make sense to me. Happy to hear what that leads to.
But for interplay of Access Control and duality of Storage Root and Storage Description, I don't have a clear faith, to be honest. This makes the Access Control mechanism complicated, or creating a special case, if they locate at the same place. In either case, we need to create a special section for Access Control Consideration, in addition to the Access Request and Grant.