LWS Protocol

The LWS Protocol defines standard interactions by which a some party can make some resources available to some agents.

• served resource - ( available resource? published resource? ) ( not defined in UCS ) A network-accessible entity exposed by a service for interaction, retrieval, or manipulation using the protocol defined in this document.
• requesting agent - ( entity in UCS ) An entity (e.g., client, user, or process) that initiates a request to interact with a servable resource.

A resource manager may keep a served resource private, may make it publicly available to anyone, or may limited its visibility to a constrained set of requesting agents .

• authentication - the process of verifying the identity of an agent executing a request.
• authorization - the process of determining whether an agent has permission to access a specific resource or perform one of a set of operations .
• resource manager - ( controller in UCS) An agent that has permission to control access to a served resource .

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY , MUST , MUST NOT , OPTIONAL , RECOMMENDED , REQUIRED , SHOULD , and SHOULD NOT in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.

A LWS REST Server is an HTTP server [ rfc9112 ] that complies with all of the relevant " MUST " statements in this specification. Specifically, the relevant normative " MUST " statements in Sections 999 REST Binding of this document MUST be respected.

A LWS REST Client is an HTTP client [ rfc9112 ] that complies with all of the relevant " MUST " statements in this specification. Specifically, the relevant normative " MUST " statements in Sections 999 REST Binding of this document MUST be respected.

The data model described in this section outlines the requirements for any concrete serialization of an authentication credential.

An authentication credential MUST include tamper evident claims about a subject, including:

• subject REQUIRED — an identifier for an end user. This MUST be a URI.
• issuer REQUIRED — an identifier for the entity that issued the authentication credential. This MUST be a URI.
• client REQUIRED — an identifier for a client application. This SHOULD be a URI.
• audience restriction RECOMMENDED — a list of values that SHOULD include an authorization server identifier.

Validation of an authentication credential requires a trust relationship between the verifier and issuer of the credential. This trust relationship MAY be established through an out-of-band mechanism. Any additional mechanisms for establishing trust between a verifier and an issuer are outlined in specific authentication suites.

An authentication credential MUST be signed. It is RECOMMENDED that the signature uses asymmetric cryptography.

Each authentication suite MUST be associated with a token type URI. An authentication suite SHOULD use a URI defined in the IANA "OAuth URI" registry.

The roles in LWS authorization are the same as those defined by OAuth 2.0 Section 1.1 [ RFC6749 ]: resource owner , resource server , client (called in this specification authorization client to avoid ambiguity), and authorization server . A storage server is a type of resource server that also conforms to the LWS storage specification.

This specification describes the interaction between a client and an authorization server as well as the interaction between a client and a conforming storage server.

The interaction between the authorization server and the storage server is out of scope of this specification. The authorization server may be the same server as the storage server or it may be a separate entity.

HTTP/2 401 Unauthorized
Link: <https://storage.example/storage_1/metadata>; rel="storageDescription"
WWW-Authenticate: Bearer as_uri="https://authorization.example",
                realm="https://storage.example/storage_1",
error=

"invalid_token"

{
    "issuer": "https://authorization.example",
    "grant_types_supported": [
        "urn:ietf:params:oauth:grant-type:token-exchange"],
    "token_endpoint": "https://authorization.example/token",
    "jwks_uri": "https://authorization.example/jwks",
    "claims_supported": [
        "sub",
        "iss",
        "client_id",
        "aud"],
    "response_types_supported": [
        "token"],
    "subject_token_types_supported": [
        "urn:ietf:params:oauth:token-type:jwt",
        "urn:ietf:params:oauth:token-type:id-token"]

}

POST /token HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fstorage.example%2Fstorage_1
&subject_token=eyJ0eXAiOiJhcytqd3QiLCJhbGciO...fiK51VwhsxJ-siBMR-YFiA
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
    "token_type":"Bearer",
    "expires_in":3600

}

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error":"invalid_request"

}

{
  "kid": "ec51c6b2",
  "kty": "EC",
  "alg": "ES256",
  "crv": "P-256",
  "typ": "at+jwt"
}
.
{
  "sub": "https://id.example/agent",
  "iss": "https://authorization.example",
  "client_id": "https://app.example/id",
  "aud": "https://storage.example",
  "exp": 1735686300,
  "iat": 1735686000,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}
.
signature

Authorization

:

Bearer
eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso

A storage description resource provides information a client can use when interacting with a storage, including descriptions of capabilities and service endpoints.

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

}

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "https://storage.example/",
  "type": "Storage",
  "capability": [{
    "type": "https://feature.example/PatchSupport",
    "mediaType": {
      "text/turtle": ["application/sparql-update"],
      "application/n-triples": ["application/sparql-update"],
      "application/linkset+json": ["application/merge-patch+json", "application/json-patch+json"]
    }
  }, {
    "type": "https://feature.example/ResumableUploads"
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "application/ld+json",
    "target": ["text/turtle", "application/n-triples"]
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "image/jpeg",
    "target": ["image/png"]
  ],
  "service": [{
    "type": "NotificationService",
    "serviceEndpoint": "https://storage.example/notification/api"
  }, {
    "type": "TypeIndexService",
    "serviceEndpoint": "https://storage.example/types/api"
  }, {
    "type": "DataSharingService",
    "serviceEndpoint": "https://storage.example/sharing/api"
  }, {
    "type": "StorageDescription",
    "serviceEndpoint": "https://storage.example/description"
  }]

}

This section delineates the abstract data model governing the organization of resources within the Linked Web Storage (LWS) system. It encompasses the structuring of containers and resources, their hierarchical interrelations, the functional semantics of containers as organizational units, rules pertaining to containment, and mechanisms for clients to organize and navigate resource collections. This model establishes the logical namespace of the storage, delineating inter-resource relationships therein, without presupposing any specific identifier structure or semantic implications derived from identifier composition. Logical organization MUST prioritize discoverability and self-descriptive APIs, avoiding hardcoded locations. Containment is represented as metadata to enable multiple containers per resource without URL changes, supporting sharing use cases. All entities MUST have associated metadata organizes resources using Link Sets (RFC 9264), distinguishing server-managed and user-managed data. 7.2 Resource In LWS, a resource constitutes the fundamental unit of storage and access. Each resource possesses a unique identifier within the system. A resource may encompass data, such as content or structured information, alongside associated metadata, including attributes like type or modification timestamps. Resources MUST be classified as 'DataResource', 'Container', or 'MetadataResource' via metadata types. DataResources MAY have multiple representations; servers MUST track original media types and support reification in metadata using the 'representation' property, which includes 'mediaType' and optional 'sizeInBytes'. 7.3 Container into containers. A container is a specialized resource capable of encompassing that holds references to other resources as resources, called its members. Containers function serve as organizational constructs, facilitating the grouping of resources in a manner akin units, analogous to collections directories or directories. collections, enabling clients to group, discover, and navigate resources. A container maintains references to its member resources, which may comprise both non-container resources and additional container resources, thereby enabling hierarchical formations. Typically, a container holds minimal intrinsic content beyond metadata or enumerations of its members; its principal role is to aggregate and structure subordinate resources. The storage system's root is designated as a container, serving as the apex organizational unit devoid of a superior parent. Containers MUST support pagination for membership listings using 'ContainerPage' types, with properties such as 'first', 'next', 'prev', and 'last'. Representations MUST use JSON-LD with a specific frame and normative context, optionally advertising content negotiation via 'Vary: Accept' headers. Storage MAY function as a root container, enabling direct writes.

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

Resources in LWS are classified as either:

• Container — a resource that contains other resources.
• DataResource — a data-bearing resource (e.g., a document, image, or structured data file).

With the exception of the root container, every resource is affiliated with precisely one parent container. This affiliation engenders a strict hierarchical structure, manifesting as a tree with a singular root container at its pinnacle. Upon creation within a designated container, The containment relationship between a new resource becomes a member of that container, appearing within and its membership enumeration. Cycles or multiple parent affiliations are prohibited within this model; a resource cannot concurrently belong to multiple containers without duplication or alternative referencing mechanisms external to container is expressed via the core containment framework. This constraint enhances model simplicity and aligns with conventional organizational paradigms. Containment rel="up" link relation. Servers MUST be modeled as metadata links using 'contains' (from include a Link header with rel="up" pointing to the parent container in responses to member) GET and 'partOf' (from member to container), allowing transitive queries HEAD requests on any non-root resource.

Link: </alice/notes/>; rel="up"

A container's members are listed in its representation using the items property. The server manages this list; clients cannot modify it directly. Membership changes occur as a side effect of resource creation and multiple hierarchies without slash semantics. Servers MAY support hierarchy arrays for ancestors. deletion.

Operations involving the creation, deletion, or relocation of resources influence container memberships as follows: The server MUST maintain containment integrity at all times:

• Upon creation, Creation : When a new resource is associated with created in a specified parent container. This association integrates container, the server MUST atomically add the resource into to the parent's membership. container's items list.
• Deletion of : When a resource entails its removal from is deleted, the server MUST atomically remove it from its parent container's membership. Should this render items list. Deleting a container requires the container devoid of members, it assumes an empty state, potentially permitting its subsequent deletion if warranted. Container deletion typically necessitates an empty state or invokes to be empty, unless recursive removal of members. deletion is explicitly requested.
• The core operations (create, read, update, delete) do not incorporate an explicit relocation or renaming function. To reassign a No orphans : Every non-root resource to an alternative container, a client may replicate or recreate MUST be reachable from the resource in root container through the target location followed containment hierarchy.
• No cycles : A container MUST NOT directly or indirectly contain itself.

Resources are identified by deletion URIs. The URI of a resource is independent of its position in the original. Implementations may optionally extend non-core operations for relocation or renaming, achievable logically through combined containment hierarchy. Servers assign URIs during resource creation and deletion. Membership is managed via create/delete operations; direct updates to membership listings MAY incorporate client hints (e.g., the Slug header), but clients SHOULD NOT assume that URI structure reflects containment.

Containment relationships are server-managed expressed through metadata ( rel="up" links and the items property in container representations), not client-writable to avoid concurrency issues. through URI path structure. This separation allows servers flexibility in URI assignment while maintaining a well-defined organizational model.

Container instantiation occurs via If a client has read access to a container, the standard resource creation operation (Section 7.1), differentiated by an indicator specifying container representation MUST include the intent identifiers for all resources contained in that container to establish a which the client has access. It MAY also contain the identifiers for resources contained in that container rather than to which the client does not have access.

A client's ability to read a non-container resource. This process yields an empty container amenable to subsequent population with members, including sub-containers listing does not imply access to extend the hierarchy. Servers contained resources themselves, and vice versa.

When a client retrieves a container, the server returns a structured container representation describing the container and its contents. This section defines the required and optional properties of a container representation.

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/notes/",
  "type": "Container",
  "totalItems": 2,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/notes/shoppinglist.txt",
      "mediaType": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "mediaType": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

This section defines the model for associating metadata with LWS resources. The LWS metadata system is based on the principles of Web Linking [ RFC8288 ], which allows servers to describe the relationships between resources using typed links. Metadata enhances discoverability, supports self-descriptive APIs, and aligns with resource operations, and container hierarchies.

Metadata Model All metadata in LWS is expressed as a set of typed links originating from a resource (the link context). Each link consists of:

• A link target: A URI identifying the related resource.
• A relation type: A string that defines the nature of the relationship.
• Optional target attributes: Additional key-value pairs that further describe the link or the target resource.

Metadata distinguishes between resources and their representations, allowing for multiple media types where applicable. For containers, metadata includes membership details and supports pagination to handle large sets efficiently. For DataResources, Data Resources, metadata includes representations, each with mediaType and optional sizeInBytes. For Containers and Data Resources we consider the link to its parent container resource to be part of the metadata of the resource.

The Linkset Resource For each resource in storage, a server MUST make metadata links available as a standalone resource according to [ RFC9264 ].

• Discovery: A resource's linkset is discoverable via a Link header with the relation rel="linkset". rel="linkset" .
• Media Type: A linkset resource MUST be available as application/linkset+json. application/linkset+json .
• Integrity: The 'linkset' link MUST point to a server-managed resource. Updates to the linkset MUST be atomic with associated resource operations to maintain consistency.

Discovering Metadata Clients discover metadata primarily through Link headers in response to GET or HEAD requests.

• Storage Description: Servers MUST support a Link header with rel="storageDescription" on relevant responses.
• Containment: Servers MUST include a Link header with rel="up" pointing to the parent container for any non-root resource.
• Preferences: Clients MAY use the Prefer header [ RFC7240 ] with the URI https://www.w3.org/ns/lws#PreferLinkRelations to include or omit specific relations.

Metadata Types

Modifiability Considerations Core metadata MAY be modified by clients. To ensure interoperability, servers MUST use standard HTTP headers to advertise their capabilities:

1. Method Discovery: Servers MUST advertise support for GET and PATCH operations on the linkset resource via the Allow header.

2. Patch Format Discovery: Servers MUST advertise support for JSON Merge Patch [ RFC7386 ] via the Accept-Patch header: Accept-Patch: application/merge-patch+json. application/merge-patch+json .

3. Optional Methods: Servers MAY support PUT or alternative patch formats; if supported, these MUST be included in the Allow and Accept-Patch headers respectively.

[!IMPORTANT] Clients SHOULD NOT assume support for PUT or specific patch formats unless they are advertised in the resource headers and MUST handle 405 Method Not Allowed or 415 Unsupported Media Type responses gracefully.

Managing Metadata Metadata is managed by interacting with the resource's associated linkset URI. Servers MUST support concurrency controls for updates.

• Partial Updates (PATCH): This is the primary mechanism for metadata management. Servers MUST support PATCH using application/merge-patch+json. application/merge-patch+json .

• Replacement (PUT): If advertised in the Allow header, a client MAY replace the entire linkset. If the server does not support PUT, it MUST reject the request with 405 Method Not Allowed.

• Restrictions: Servers MAY restrict modifications to specific links (like partOf up or contains) items ) to maintain system integrity. If a server restricts partOf modifications, it MUST document this in its conformance statement.

• Lifecycle: Metadata lifecycles are tied to the described resource; deleting a resource MUST result in the automatic removal of its associated linkset metadata.

The create resource operation adds a new served resource to an existing container . This operation handles both the creation of data resources (files) and sub-containers.

Inputs:

• Target container: The identifier of the container where the new resource will be created.
• Identity hint: An optional suggestion for the new resource's identifier. The server may use this hint but is not required to.
• Content: The initial content and type for the new resource.

Behavior:

• Identity generation: The server determines the final identifier (URI) for the new resource. If an identity hint was provided, the server attempts to incorporate it while ensuring uniqueness and validity within the container. If no hint is provided, the server generates a unique identifier.
• Container membership update: The server atomically adds the new resource to the membership listing of the target container.
• Metadata initialization: The server initializes system metadata for the new resource. If the resource has an associated metadata resource it is also initialized.

Possible Responses:

• Created: The operation succeeded. The server returns the final identifier of the newly created resource.
• Target Not Found: The specified target container does not exist.
• Not Permitted: The client's identity is known, but they do not have permission to create resources in this container.
• Unknown Requester: The server does not recognize the client's identity and requires authentication.
• Conflict: A resource with the generated identifier already exists, or there is another state conflict.
• Unknown Error: An unexpected internal error occurred.

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. 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 Web Linking in [ RFC8288 ]. Server-managed metadata MUST be generated automatically by the server upon creation and MUST NOT be overridden by client-provided links.

On success, the server MUST return the 201 status code with the new URI in the Location header. The server MUST include Link headers for key server-managed metadata, such as including a link to the parent container (rel="partOf"), a link to the ACL resource (rel="acl"), ( rel="up" ), and a link to its the created resource's dedicated linkset resource (rel="linkset"; type="application/linkset+json"). ( rel="linkset"; type="application/linkset+json" ). Additional links SHOULD include rel="type" (indicating Container https://www.w3.org/ns/lws#Container or DataResource) and rel="mediaType" if applicable. https://www.w3.org/ns/lws#DataResource ). The body MAY be empty or include a minimal representation of the resource. All metadata creation and linking MUST be atomic with the resource creation to maintain consistency.

POST (to a container URI) – Create with server-assigned name: Use POST to add a new resource inside an existing container. The server assigns an identifier to the resource, optionally suggested via the Slug header. The server MAY honor the Slug header if it does not conflict with naming rules or existing resources. Clients indicate the type of resource to create as follows:

• To create a Container , the client MUST include a Content-Type Link header in the request with rel="type" pointing to indicate the media type of Container type: Link: <https://www.w3.org/ns/lws#Container>; rel="type" .
• To create a DataResource , the new resource, enabling client includes the server to distinguish between resource types. Specifically, servers MUST interpret the Content-Type as follows: if it matches the LWS-defined media type for containers (application/lws+json), content in the server creates a Container; otherwise, it creates a DataResource request body with the specified media type. appropriate Content-Type header.

Example (POST to create a new data resource):

POST /alice/notes/ HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Content-Type: text/plain
Content-Length: 47
Slug: shoppinglist.txt
milk
eggs
bread
butter
apples
orange juice

In this example, the client is posting to the container /alice/notes/ . It provides text/plain content (a grocery list) and suggests the name shoppinglist.txt for the new resource. If /alice/notes/ exists and the client is authorized, the server will create a new DataResource (based on the Content-Type), generate associated metadata, and link add it via to the linkset. container's membership.

Example (Response to POST): POST — Data Resource):

HTTP/1.1 201 Created
Location: /alice/notes/shoppinglist.txt
Content-Type: text/plain; charset=UTF-8
"def789012"

Link: </alice/notes/shoppinglist.txt.meta>; rel="linkset"; type="application/linkset+json"
</alice/notes/>; rel="partOf"
</alice/notes/shoppinglist.txt.acl>; rel="acl"

Link: </alice/notes/>; rel="up"
Link: <https://www.w3.org/ns/lws#DataResource>; rel="type"
Content-Length: 0

On success, return 201 Created with the new URI in the Location header. The body may be empty or a minimal representation. Include relevant headers such as Content-Type matching the created resource; Content-Length: 0 indicates no body. Server responses MUST use entity tags for responses that contain resource representations or successful responses to HEAD requests, enabling concurrency control in subsequent operations. If the target container /alice/notes/ does not exist, the server MUST return a 404 error status unless another status code is more appropriate.

Creating Containers: To create a new container via the REST API, container, a client uses POST to an existing parent container, container with the Content-Type header set to the LWS-defined media type a application/lws+json Link to indicate container creation. The body MAY be empty. Servers MUST support creation of containers using this media header indicating the Container type. For example:

POST /alice/ HTTP/1.1
Host: example.com
Authorization: Bearer <token>
application/lws+json

Content-Length: 0
Slug: notes
Link: <https://www.w3.org/ns/lws#Container>; rel="type"

Example (Response to POST — container):

HTTP/1.1 201 CreatedLocation: /alice/notes/Link: </alice/notes/.meta>; rel="linkset"; type="application/linkset+json"Link: </alice/>; rel="up"Link: <https://www.w3.org/ns/lws#Container>; rel="type"Content-Length: 0

This would create creates a new container at /alice/notes/ , with server-generated metadata including rel="type" as https://www.w3.org/ns/lws#Container . .

Additional notes on Create (HTTP binding):

• POST is not idempotent. Repeating it may create duplicates; clients SHOULD avoid unintentional retries or use unique identifiers/checks to prevent this.
• Servers MUST distinguish between DataResource and Container types in metadata upon creation, based on the Content-Type header in the request. Metadata updates are atomic; servers MUST ensure the linkset resource is created and populated with mandatory server-managed fields before returning success.
• For discoverability, servers SHOULD include a Link header with rel="storageDescription" on 401 responses to guide clients without hardcoded URIs.

Managing and Retrieving Metadata (Related to Creation): While metadata is primarily retrieved via read operations, it is generated during creation. Clients can immediately retrieve it post-creation using GET or HEAD on the new resource URI. Clients can use the Prefer header to request inclusion of specific metadata links (via relation types) and attributes.

Retrieves the representation of an existing resource or the listing of a container.

• Inputs : Target identifier and optional parameters.
• Behavior :
  • For non-container resources, the server returns the resource content.
  • For containers, the server returns a listing of member resources. resources which MAY be filtered based on authorization . Listings must include core metadata for each member and must be filtered based on the requester's permissions. member.
• Outcome : The requested representation or a notification of failure.

The read resource operation requests a resource representation with HTTP GET requests (and HEAD for header-only requests). The behavior differs depending on whether the target URL is a container or a non-container resource (DataResource). Servers MUST distinguish resource types via metadata. All responses MUST integrate with metadata as defined in Section 8.1, including Link headers for key relations such as rel="linkset", rel="acl", rel="partOf", rel="linkset" , rel="up" , and rel="type". rel="type" . Servers MUST ensure atomicity between the resource state and its metadata during reads.

GET (non-container resource) – Retrieve a resource’s resource's content: Send GET to the resource URI for full content (if authorized). Respond with 200 OK, body containing the data, and Content-Type matching the stored media type. Servers MUST support range requests per [ RFC7233 ] for partial retrieval. Responses MUST include an ETag header for concurrency control and caching.

Example (GET a file):

GET /alice/notes/shoppinglist.txt HTTP/1.1
Authorization: Bearer <token>
Accept: text/plain

This requests the content of /alice/notes/shoppinglist.txt , indicating that the client wants it in text form. Assuming the resource exists, is text, and the client has access:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 34
ETag: "abc123456"
Link: </alice/notes/shoppinglist.txt.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/notes/>; rel="up"
Link: <https://www.w3.org/ns/lws#DataResource>; rel="type"
milk
cheese
bread
guacamole
soda
chocolate bars
hash
eggs

The server returned the text content (34 bytes in total, as indicated by Content-Length ). The content is exactly the stored data in the file. The ETag: "abc123456" is a version identifier for caching or concurrency purposes. The response includes Link headers for metadata discoverability, with mandatory fields such as partOf, acl, up and type. type .

GET (container resource) – List a container’s container's contents: When the target URI corresponds to a container (determined via metadata type), a GET request will return returns a listing of the container’s members rather than raw content. Servers MUST support pagination for large memberships, container's members. The response body is a container representation as defined in the Container Representation section, using query parameters or headers to return partial listings with links to subsequent pages, responding with 206 Partial Content for paginated responses. Listings MUST include the LWS container media type. The listing includes metadata for each member: resource IDs identifiers ( MUST ), types as an array of system and user-defined ( MUST ), representations with mediaType and optional sizeInBytes media types ( MUST for DataResources), modified sizes ( SHOULD ), and modification timestamps ( SHOULD ).

Example (GET a container with JSON-LD): container):

GET /alice/notes/ HTTP/1.1
Authorization: Bearer <token>
Accept: application/ld+json

Assuming the container exists and the client has access:

HTTP/1.1 200 OK
Content-Type: application/lws+json
ETag: "container-etag-789"
Link: </alice/notes/.meta>; rel="linkset"; type="application/linkset+json"
Link: </alice/>; rel="up"
Link: <https://www.w3.org/ns/lws#Container>; rel="type"
{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "/alice/notes/",
  "type": "Container",
  "totalItems": 2,
  "items": [
    {
      "type": "DataResource",
      "id": "/alice/notes/shoppinglist.txt",
      "mediaType": "text/plain",
      "size": 47,
      "modified": "2025-11-24T12:00:00Z"
    },
    {
      "type": ["DataResource", "http://example.org/customType"],
      "id": "/alice/notes/todo.json",
      "mediaType": "application/json",
      "size": 2048,
      "modified": "2025-11-24T13:00:00Z"
    }
  ]
}

In this example, /alice/notes/ is a container. The response uses JSON-LD with a normative the LWS context, listing members with required metadata. For large containers, the response might include a "next" property Each item includes its type , id , mediaType , size , and use 206 Partial Content. modified timestamp as flat properties.

In all cases, the server MUST include the following metadata in the response headers: an ETag (representing the listing version, which changes on membership modifications), and Link headers with rel="type" indicating it is a container, rel="linkset", rel="partOf", rel="linkset" and rel="acl". rel="up" .

HEAD (any resource or container) – Headers/metadata only: The LWS server MUST support HEAD [ RFC9110 ] for both containers and non-containers, returning the same headers as GET (including ETag, Content-Type, Link for metadata) but without a body. This enables metadata retrieval without transferring content.

Caching and Conditional Requests: LWS leverages HTTP caching semantics. Servers MUST support conditional requests via If-None-Match (with ETags) or If-Modified-Since headers. If the resource or container listing has not changed, respond with 304 Not Modified to avoid redundant transfers. ETags MUST be provided in all GET/HEAD responses for concurrency and caching support.

Discoverability and Authorization: For enhanced discoverability, servers SHOULD include WWW-Authenticate headers on 401 Unauthorized responses with parameters to guide clients without hardcoded URIs. Metadata links SHOULD be included where applicable.

Modifies the state of an existing [served resource] via full replacement or a partial patch.

• Inputs : Target identifier, new content, and optional concurrency constraints.
• Behavior : The server applies the changes atomically. If concurrency constraints are provided, the update is rejected if the resource has been modified since it was last read by the requester.
• Outcome : Confirmation of the update or a notification of conflict.

The update resource modifies the contents of an existing served resource by a PUT request (to replace the entire resource) or a PATCH request (to apply a partial modification). The client must have write access to the resource’s URL to perform these operations. Note: This section describes updating a resource's primary content. To update its metadata, see Section 9.3.2. LWS servers MUST handle PUT and PATCH requests on resource URIs as modifications to the resource content only, with no default impact on the associated linkset. To optionally update both content and metadata in a single atomic operation, clients MAY include Link headers in the PUT/PATCH request to the resource URI and specify the preference 'Prefer: set-linkset' (as defined in RFC 7240). In this case, the server MUST interpret the provided Link headers as a replacement (for PUT) or partial update (for PATCH) to the linkset, in addition to applying the content changes. This behavior is OPTIONAL for servers but, if supported, MUST be invoked explicitly via the Prefer header to prevent unintentional metadata overwrites. Servers that do not support combined updates MUST ignore the preference or respond with 501 Not Implemented.

PUT (replace full resource) – Send PUT to the resource URI with new full content in the body and matching Content-Type (generally consistent with existing type). PUT is idempotent for existing resources. For safety, include If-Match with current ETag (per Section 7.3 concurrency); mismatch yields 412 Precondition Failed or 409 Conflict. Without checks, updates are unconditional but risk overwriting concurrent changes. If a server supports Etags for a resource, it MUST reject unconditional PUT requests that lack an If-Match header with a 428 Precondition Required response.

Example (PUT to update a resource):

PUT /alice/personalinfo.json HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
If-Match: "abc123456"
{
"name": "Alice",
"age": 30,
"city": "New London",
"state": "Connecticut"
}

In this example, the client is updating an existing JSON resource at /alice/personalinfo.json. It includes an If-Match header with the ETag "abc123456" that it got from an earlier GET or HEAD request. The server will compare that to the current ETag; if they match, it proceeds to replace the content with the JSON provided. If they don’t match, the server rejects the update (because the resource was changed by someone else in the meantime). Successful response: If the update succeeds, the server can respond with 200 OK and possibly include the updated representation or some confirmation (like the new content or a part of it). Alternatively, the server may respond with 204 No Content to indicate success with no body (especially common if no further info needs to be conveyed). In either case, the server SHOULD include a new ETag to signify the new version, and maybe a Content-Type if a body is returned. For example:

HTTP/1.1 204 No Content
ETag: "def789012"

This tells the client the update went through and provides the new ETag . If the server chose to return the updated content, it might use 200 OK and include the JSON in the body, along with headers.

• Error responses: If the If-Match did not match (concurrent modification), the server could return 412 Precondition Failed (meaning the precondition header failed) or 409 Conflict – our earlier abstract description used Conflict for concurrency issues, and 409 is a natural mapping for that scenario. If the resource did not exist, a PUT meant as an update will result in 404 Not Found (unless the intent was to create, but typically clients use PUT for create only when they are sure of what they’re doing, or they use it as upsert without If-Match). If the client is not authorized, 403 Forbidden (or 401 Unauthorized if no valid credentials were provided). If the request payload is not valid, 400 Bad Request .

PATCH (partial update) – The HTTP PATCH method [ RFC5789 ] allows a client to specify partial modifications to a resource, rather than sending the whole new content. This is useful for large resources where sending the entire content would be inefficient if only a small part changed, or for concurrent editing where you want to apply specific changes. LWS server MUST minimally support JSON Merge Patch (application/merge-patch+json) as defined in [ RFC7386 ].

Update Resource Metadata (HTTP PUT / PATCH on Linkset) A resource's metadata is updated by modifying its corresponding linkset resource, discovered via the Link header with rel="linkset". Full Replacement (PUT): A PUT request to the linkset URI with a complete linkset document in the body replaces all metadata for the resource. Partial Update (PATCH): A PATCH request to the linkset URI adds, removes, or modifies specific links.

Concurrency Control for Metadata Because a resource's metadata can be modified by multiple actors, preventing concurrent overwrites is critical. To ensure data integrity, LWS servers and clients MUST implement optimistic concurrency control using conditional requests [ RFC7232 ] for all PUT and PATCH operations on a linkset resource. Server Responsibilities: A server MUST include an Etag header in its responses to GET and HEAD requests for a linkset resource. Upon a successful PUT or PATCH on the linkset, the server MUST generate a new, unique Etag value for the modified linkset and return it in the Etag header of the response. Client Responsibilities: When modifying a linkset resource, a client MUST include an If-Match header containing the most recent Etag it received for that resource. Processing Rules: If the If-Match header value does not match the linkset's current Etag, the server MUST reject the request with a 412 Precondition Failed status code. If the If-Match header is missing from a PUT or PATCH request to a linkset URI, the server MUST reject the request with a 428 Precondition Required status code [ RFC6585 ]. Example (PUT to replace a linkset): A client first fetches the linkset and receives its ETag.

GET /alice/personalinfo.json.meta HTTP/1.1
Authorization: Bearer <token>
Accept: application/linkset+json
HTTP/1.1 200 OK
Content-Type: application/linkset+json
ETag: "meta-v1"
{
  "linkset": [
    {
      "anchor": "/alice/personalinfo.json",
      "describedby": [ { "href": "/schemas/personal-info.json" } ]
    }
  ]
}

The client now wants to add a license. It constructs a new, complete linkset document and sends a PUT request with the If-Match header.

PUT /alice/personalinfo.json.meta HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/linkset+json
If-Match: "meta-v1"
{
  "linkset": [
    {
      "anchor": "/alice/personalinfo.json",
      "describedby": [ { "href": "/schemas/personal-info.json" } ],
      "license": [ { "href": "https://creativecommons.org/licenses/by/4.0/" } ]
    }
  ]
}

If successful, the server responds with success and the new ETag.

HTTP/1.1 204 No Content
ETag: "meta-v2"

Summary of Update Rules If you want to change only the content of a resource → PUT/PATCH the resource itself. If you want to change only the links (metadata) of a resource → PUT/PATCH the resource’s associated linkset resource. If you want to change both content and links → PUT/PATCH the resource itself, including the appropriate Link headers AND 'Prefer: set-linkset'. Setting both is off by default.

Permanently removes a resource and its associated metadata.

• Inputs : Target identifier, an optional recursive flag (for containers), and optional concurrency constraints.
• Behavior :
  • For non-container resources, the server removes the content, metadata, and updates the parent container's membership.
  • For containers, the server typically requires the container to be empty unless a recursive delete is explicitly requested and supported.
• Outcome : Confirmation of removal or a notification of failure.

The delete resource operation is implemented using the HTTP DELETE method, as defined in the abstract operation above. This section specifies the HTTP bindings for inputs, behaviors, and responses.

The DELETE request targets the URI of the resource or container to remove. Clients MAY include an If-Match header with an ETag for concurrency checks, as described in checks.

Deletion and Containment: When a resource is deleted, the abstract operation. server MUST atomically remove it from its parent container's items list. The parent container's totalItems count and ETag MUST be updated accordingly.

For non-container resources, the server processes removes the deletion as specified resource content, its associated metadata (linkset), and the containment reference in the abstract behavior. parent container.

For container resources, the server defaults to non-recursive deletion. If recursion the container is desired not empty and supported, clients recursion is not requested, the server MUST reject the request with 409 Conflict. Servers MAY support recursive deletion of all contained resources within the container that is being deleted. Clients MUST use the Depth: infinity header, header to request for a recursive delete, as defined in [ RFC4918 ]. Servers that do not support recursion MUST reject such requests with 501 Not Implemented.

On success, the server MUST respond with 204 No Content. Servers SHOULD support concurrency checks via If-Match with ETags; mismatches MUST yield 412 Precondition Failed. conditional requests, as defined in [ RFC9110 ].

If the client lacks authorization, the server MUST return 403 Forbidden (if the client's identity is known but permissions are insufficient) or 401 Unauthorized (if no valid authentication is provided). In cases where revealing resource existence poses a security risk, the server MAY return 404 Not Found instead.

Example (DELETE a non-container resource):

DELETE /alice/notes/shoppinglist.txt HTTP/1.1
Authorization: Bearer <token>
If-Match: "abc123456"

Assuming the ETag matches and the client is authorized, the server deletes the resource, its metadata, and updates removes it from the containing parent container /alice/notes/ atomically:

HTTP/1.1 204 No Content

Example (DELETE a non-empty container without recursion):

DELETE /alice/notes/ HTTP/1.1
Authorization: Bearer <token>

Assuming /alice/notes/ contains resources, the server refuses the deletion:

HTTP/1.1 409 Conflict
Content-Type: text/plain
Cannot delete container /alice/notes/ - container is not empty.

Example (DELETE a container with recursion, if supported):

DELETE /alice/notes/ HTTP/1.1
Authorization: Bearer <token>
Depth: infinity

Assuming the server supports recursion and the client has permissions for all contents, the server deletes the container and its descendants atomically:

HTTP/1.1 204 No Content

This table maps generic LWS responses (from Section 8) to HTTP status codes and payloads for consistency, incorporating specific scenarios such as pagination, concurrency controls, quota constraints, and metadata integration:

LWS container representation and storage description resource MUST use the media type application/lws+json .

While LWS container representations use JSON-LD conventions, the constraints and requirements for LWS justify the use of a specific media type. Because LWS containers can be considered a restricted profile of JSON-LD, implementations SHOULD consider the application/ld+json; profile="https://www.w3.org/ns/lws/v1" media type as equivalent to application/lws+json .

Define mechanisms for content negotiation based on profiles, allowing clients to request specific representations or views of resources (e.g., JSON-LD contexts, different RDF serializations, or application-specific profiles).

this left intentionally blank

Define notification mechanisms that allow clients to be informed of changes to resources, including subscription models, event formats, and delivery mechanisms.

this left intentionally blank

Define inbox resources with specific semantics within LWS, including message posting, retrieval, and management capabilities for asynchronous communication patterns.

this left intentionally blank