LWS Storage Description Resource #53
Conversation
| </li> | ||
| <li> | ||
| <dfn>type</dfn> - the <code>type</code> property is REQUIRED. Its value MUST be a string that equals | ||
| <code>Storage</code> or a set of strings that contains an item equal to <code>Storage</code>. |
There was a problem hiding this comment.
Is this a case-sensitive requirement? Or would a string equal to storage work?
There was a problem hiding this comment.
Also, is there a reason not to require an lws-based URI, allowing for follow-your-nose discovery of what https://www.w3.org/ns/lws#storage (or lws:storage) means?
There was a problem hiding this comment.
my understanding is that the text is focusing on the surface syntax (application/lws+json in this case). But yes, since that surface syntax is JSON-LD, this would resolve to the IRI lws:Storage...
+1 to mention explicitly that it is case-sensitive.
| where each service is described by a map containing the following properties. Additional properties MAY be present. | ||
| <ul> | ||
| <li><dfn>id</dfn> - the <code>id</code> property is OPTIONAL. If present, its value MUST be a URI.</li> | ||
| <li><dfn>type</dfn> - the <code>type</code> property is REQUIRED. Its value MUST be a string or a set of strings.</li> |
| <h3>Storage Description Resource</h3> | ||
|
|
||
| <p> | ||
| A storage description resource provides information a client can use when |
There was a problem hiding this comment.
| A storage description resource provides information a client can use when | |
| A storage description resource provides information a client can use |
("when" is duplicated in the next line)
| </li> | ||
| <li> | ||
| <dfn>type</dfn> - the <code>type</code> property is REQUIRED. Its value MUST be a string that equals | ||
| <code>Storage</code> or a set of strings that contains an item equal to <code>Storage</code>. |
There was a problem hiding this comment.
my understanding is that the text is focusing on the surface syntax (application/lws+json in this case). But yes, since that surface syntax is JSON-LD, this would resolve to the IRI lws:Storage...
+1 to mention explicitly that it is case-sensitive.
| <h4>Discovery and Binding</h4> | ||
|
|
||
| <p> | ||
| All responses to <code>GET</code> and <code>HEAD</code> requests targeting storage resources MUST include a |
There was a problem hiding this comment.
Does "storage resources" mean the "storage" (as a resource), or any resources contained in the storage?
If case 1, how do I discover the location of the storage when only knowing the link of a (regular) resource which I have permission to read / GET?
Should this not be discussed in this document, either it is supported in the spec (due to what reason), or how it can be performed?
(I remember this was mentioned in a meeting, but cannot recall what the conclusion was. Sorry for duplicating, but just don't want this to be forgotten.)
There was a problem hiding this comment.
A storage resource is any resource whose lifecycle is manged by a storage, including the root storage resource itself. That is, every resource in a storage is a 'storage resource'. This means that all resources in a storage will include a link to the storage metadata resource.
| capabilities, where each capability is described by a map containing the following properties. | ||
| Additional properties MAY be present. | ||
| <ul> | ||
| <li><dfn>id</dfn> - the <code>id</code> property is OPTIONAL. If present, its value MUST be a URI.</li> |
There was a problem hiding this comment.
There is no usage of the id field in the examples, nor explanations on why this is important/distinct. Should this simply be removed, as considered part of the "additional properties"?
There was a problem hiding this comment.
I do not have a strong opinion about the id field. Here, I was mostly following patterns that I see elsewhere related to JSON-LD structures. The main reason to mention this field is to ensure that it is a URI, but realistically, that requirement could easily be described by the relevant capability or service definition.
| <dfn>service</dfn> - the <code>service</code> property is OPTIONAL. Its value MUST be a set of services, | ||
| where each service is described by a map containing the following properties. Additional properties MAY be present. | ||
| <ul> | ||
| <li><dfn>id</dfn> - the <code>id</code> property is OPTIONAL. If present, its value MUST be a URI.</li> |
There was a problem hiding this comment.
As above, for the necessity of the id field.
|
|
||
| <pre id="example-storage-description-minimal" class="example" title="Minimum storage description resource"> | ||
| { | ||
| "@context": "https://www.w3.org/ns/lws/v1", |
There was a problem hiding this comment.
The context is https://www.w3.org/ns/lws/v1 here. So the service description type is https://www.w3.org/ns/lws/v1/StorageDescription?
But the rel parameter's corresponding value is https://www.w3.org/ns/lws#storageDescription (all the ontology/namespace is different, the way the object URI is composed is different, and the object is different). Is this an intentional difference?
There was a problem hiding this comment.
The @context is not a namespace prefix. Rather, it maps JSON fields and values to URIs.
That is, the service description type is an rdfs:Class defined as https://www.w3.org/ns/lws#StorageDescription (no v1 in the URL).
The https://www.w3.org/ns/lws#storageDescription URI is an rdf:Property used in a link header.
The first one describes an instance of a storage description while the second points to an instance of a storage description.
In general, I find the minor difference between s and S to be confusing, and I would like a terms that are more clearly different, but I think we can sort out the specific URIs that we use separately.
| "id": "https://storage.example/root/", | ||
| "type": "Storage", | ||
| "capability": [{ | ||
| "type": "https://feature.example/PatchSupport", |
There was a problem hiding this comment.
Related to this example: is there an intention to also standardize a way to specify the scope of the resources that the capability applies? E.g., Patch can be applied to certain resources, but not some other resource (or any combinations)?
Rationale of this: does the same list of capabilities always apply across all resources within the storage, or not?
There was a problem hiding this comment.
The intention is to describe features or capabilities that apply to an entire storage. If there are features that apply only to certain resources, those descriptions might be better suited to resource metadata.
In principal, a capability definition could include a scope (e.g., all resources in the /02db96dd container), but I don't know that we need to define that here.
This feature describes the requirements for a storage description resource.
This is a class 4 change to the LWS protocol and will require a WG vote. This proposal represents discussions from the face-to-face meeting on 2025-10-08 and the WG meeting on 2025-12-15.
Preview | Diff