Initial CRUD with proposed metadata handling #37

ebremer · 2025-09-12T14:57:32Z

Preview | Diff

REST Binding

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Co-authored-by: Jesse Wright <[email protected]>

Co-authored-by: Ted Thibodeau Jr <[email protected]>

jeswr · 2025-09-13T13:52:42Z

.github/workflows/add_prs_and_issues_to_project.yml

@ebremer - do you know why all of these files are appearing in the diff when there don't seem to be any changes?

For several, it's whitespace. Probably line endings.

I moved different sections into sub folders to avoid having one folder with everything.

…into crudandmeta

TallTed · 2025-09-29T23:24:14Z

I'm curious about the removal of slash semantics. For some years, ending a resource identifier with a slash in its creation has been the way to indicate that the user wants it to be a container. How does a user indicate this desire without the slash semantics?

gibsonf1 · 2025-09-30T02:27:51Z

I'm curious about the removal of slash semantics. For some years, ending a resource identifier with a slash in its creation has been the way to indicate that the user wants it to be a container. How does a user indicate this desire without the slash semantics?

@TallTed I think the solid spec uses the link header to determine if a new resource should be a container with no reference to the slash semantics. For TrinPod, we only look for http://www.w3.org/ns/ldp#BasicContainer; and http://www.w3.org/ns/ldp#Container; in the link header to set as a container or not.

TallTed · 2025-09-30T21:11:34Z

I think the solid spec uses the link header to determine if a new resource should be a container with no reference to the slash semantics. For TrinPod, we only look for http://www.w3.org/ns/ldp#BasicContainer; and http://www.w3.org/ns/ldp#Container; in the link header to set as a container or not.

I think I remember this slash pattern from LDP spec development, where one of the goals was to enable full functionality with simple tools like curl (where you can specify headers and their values, but doing so is a rather heavier load than putting a slash on the end of a container target). I think it's not the link header, but the media-type header, that matters for uploads (PUT) or creates (POST).

I think something along the lines of the sentences above should be added to the LWS spec, i.e., replace the previously available "Just put a slash at the end!" pattern with a "just include this header with this value. For example, use this flag and this argument with curl!"

…sent day

…into crudandmeta

elf-pavlik · 2025-12-01T15:04:20Z

lws10-core/Rest-Binding/rest-create-resource.md

@@ -0,0 +1,135 @@
+### Create Resource (HTTP POST)
+
+New resources are created using POST to a target container URI, with the server assigning the final identifier. Clients MAY suggest a name via the Slug header, but servers MUST have authority over naming to ensure uniqueness and compliance with policies. PUT is reserved for updates to existing resources and MUST NOT be used for creation in this version of the specification, to prioritize server-managed identifiers and simplify client-server interactions. Clients MAY provide initial user-managed metadata for the new resource by including one or more Link headers in the POST request, following the syntax of [RFC 8288]. Server-managed metadata MUST be generated automatically by the server upon creation and MUST NOT be overridden by client-provided links.


Is there a plan to support create with PUT/PATCH, using conditional requests.
Since Slug header can't be relied on, there doesn't seem to be a way for the client to create at specific location. This makes it harder to build offline-first application since resources can't be fully interlinked locally before syncing them with the web storage.

This probably isn't the best place to discuss it. I will find existing use case or add a new one for creating linked resources offline and bring it up later. The can be other ways to address it.

acoburn

I haven't finished my review, but this covers much of the text.

acoburn · 2025-12-22T15:40:41Z

lws10-core/Operations/create-resource.md

@@ -0,0 +1,21 @@
+### Create Resource Operation
+The *create resource* operation requests the creation of a new resource on the server. The resource can be a non-container (data) resource or a container (collection) resource. The operation mandates that the server assigns a new identifier within a target container (like creating a new file in a folder); client-specified full identifiers are not supported for creation in this version to ensure server authority over naming and to simplify interactions.


"Client-specified full identifiers are not supported..." This could be interpreted as "a server MUST NOT", which is probably not what is meant here.

acoburn · 2025-12-22T15:43:41Z

lws10-core/Operations/create-resource.md

+* **Target container identifier:** The identifier of an existing container where the new resource will be created as a member.
+* **Resource content:** The content to store in the resource (binary or text). This is optional to allow creation of an empty container or an empty resource.
+* **Suggested name:** An optional hint for naming. The server MAY incorporate this if it does not conflict with naming rules or existing resources.
+* **Media type:** The MIME media type or format of the content. This helps the server understand how to store and serve the content. It MUST be provided when content is included and MAY be omitted for empty containers.


Suggested change

* **Media type:** The MIME media type or format of the content. This helps the server understand how to store and serve the content. It MUST be provided when content is included and MAY be omitted for empty containers.

* **Media type:** The media type or format of the content. This helps the server understand how to store and serve the content. It MUST be provided when content is included and MAY be omitted for empty containers.

If LWS defines a media type for containers (e.g. application/lws+json), this could be used to indicate that a container is to be created. This would simplify the requirement.

acoburn · 2025-12-22T15:46:21Z

lws10-core/Operations/create-resource.md

+* **Media type:** The MIME media type or format of the content. This helps the server understand how to store and serve the content. It MUST be provided when content is included and MAY be omitted for empty containers.
+
+**Behavior:**
+* The server MUST create a new resource as a member of the specified target container, assigning the identifier (potentially incorporating the suggested name). The new resource is then added to the specified container’s member list via metadata updates.


It's unclear what you mean by "via metadata updates" -- is it a separate operation? Would it suffice to just say "The new resource is then added to the specified container's member list"?

acoburn · 2025-12-22T15:50:20Z

lws10-core/Operations/create-resource.md

+* The server MUST create a new resource as a member of the specified target container, assigning the identifier (potentially incorporating the suggested name). The new resource is then added to the specified container’s member list via metadata updates.
+* Upon creation, servers MUST generate a metadata resource linked via Link Sets (RFC 9264), including mandatory server-managed fields such as type (https://www.w3.org/ns/lws#Container or https://www.w3.org/ns/lws#DataResource), mediaType (if applicable), ACL reference, and partOf (linking to the target container). User-managed metadata MAY be provided by the client, but server-managed fields MUST NOT be overridden.
+* The server **MAY** enforce additional constraints on creation, such as size limits, quota checks, or restrictions on allowed media types. If any such constraint is violated, the server will reject the operation with an appropriate error.
+* The creation MUST be atomic, including metadata generation and container membership updates—if any step fails, no new resource or metadata is created (or any partial artifacts are cleaned up). The identifier of the newly created resource **MUST** be returned to the client (so the client knows how to refer to it).


Suggested change

* The creation MUST be atomic, including metadata generation and container membership updates—if any step fails, no new resource or metadata is created (or any partial artifacts are cleaned up). The identifier of the newly created resource **MUST** be returned to the client (so the client knows how to refer to it).

* The creation MUST be atomic, including metadata generation and container membership updates—if any step fails, no new resource or metadata is created. The identifier of the newly created resource **MUST** be returned to the client (so the client knows how to refer to it).

The statement "no new resource or metadata is created" should suffice here.

acoburn · 2025-12-22T15:52:37Z

lws10-core/Operations/create-resource.md

+**Possible Responses:** *(on the abstract operation level, not tied to a specific protocol)*
+* **Created:** The operation succeeded in creating a new resource. The response includes the new resource’s identifier and possibly a minimal representation or metadata.
+* **Bad Request:** The request was malformed or violated constraints. The resource was not created.
+* **Not Permitted:** The client is not authorized to create a resource in the target location.
+* **Not Found:** The specified target container does not exist or cannot be found. This could also be treated as a type of Bad Request or Not Permitted, depending on the cause.
+* **Unknown Error:** An internal server error occurred, or some unexpected condition prevented the creation. This is a catch-all for failures not covered by more specific errors. The response would indicate that the server failed the operation (and ideally include an error message or code).


Is this an exhaustive list? Could there be other responses? I think it would be good to allow other possible responses.

acoburn · 2025-12-22T21:26:23Z