[@@ from charter]
The Linked Web Storage Protocol specification aims to provide applications with secure and permissioned access to externally stored data in an interoperable way.
The Linked Web Storage Protocol does/does not include protocol details for integration with identity layers and mechanisms; access management and data integrity; notifications about resource changes; and authorization mechanisms.
This is an unofficial proposal.
Introduction
Resource Access
The LWS Protocol defines standard interactions by which 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.
Security and Privacy
A resource manager may keep a served resource private, may make it publicly available to anyone, or may limit 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.
Terminology
The terms "authorization server" and "client" are defined by the OAuth 2.0 Authorization Framework [[!RFC6749]].
The terms "end-user" and "issuer" are defined by OpenID Connect Core 1.0 [[!OPENID-CONNECT-CORE]].
This specification defines the following terms:
- agent — a person, social entity, or software identified by a URI.
- authentication credential — a security token that asserts claims about an agent or end-user. This token is secured with a cryptographic proof.
Examples of authentication credentials include assertions of identity such as OpenID Connect ID Tokens and SAML-based assertions as well as assertions of
capability such as ZCAPs.
- authentication suite — a defined validation mechanism for a concrete serialization of an authentication credential.
- auxiliary resource — an LWS resource whose lifecycle is bound to an LWS resource, called its principal resource.
- LWS resource — an HTTP resource as defined in [[[RFC9110]]] which supports the read operations defined by the Linked Web Storage Protocol.
Following [[[RFC9110]]], this specification "does not limit the nature of a [LWS] resource; it merely defines an interface that might be used to interact with [LWS] resources." [[RFC9110]]
- container — an LWS resource that is able to enumerate a collection of LWS resources, conforming to the conventions described in Section 8. Containers. The ability to create new resources in a container or to delete an existing container follows the requirements outlined in Section 9. Operations.
- data resource — a data-bearing LWS resource such as a document, image, or structured information whose support for update and delete operations follows the requirements outlined in Section 9. Operations.
- containment — the relationship between a container and the LWS resources whose lifecycle the container manages.
- linkset resource — a type of auxiliary resource whose representation conforms to [[[RFC9264]]]. Update operations for linkset resources follow the requirements outlined in Section 9. Operations.
- metadata resource — an auxiliary resource, managed by a storage, that describes an LWS resource and conforms to the conventions described in TBD. The lifecycle of a metadata resource is bound to the LWS resource it describes.
- resource — a resource is, as described by [[WebArch]] and [[RFC3986]], “whatever might be identified by a URI”. Resources whose essential characteristics can be conveyed in a message (such as web pages, images, structured data objects...) are called information resources [[WebArch]].
- storage — a set of hierarchically organized HTTP resources whose lifecycle is managed by the conventions described by the Linked Web Storage Protocol. A storage is described by a storage description resource which references a collection of services that provide affordances over those resources.
- storage controller — an agent that controls all resources in a storage.
- storage description — an LWS resource that enumerates and describes the storage root along with services and capabilities of a storage. Its representation conforms to the storage description data model.
- 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 principal resource.
This specification defines operations on served resources, the resulting change of state, and a response intended to give the requesting agent requested infomation or inform them of the outcome of the operation.
An operation is any of the following actions that can be performed on a served resource:
- create resource -
- read resource -
- update resource -
- delete resource -
The folowing section will describe the semantics and responses of these operations but the following core responses apply to any operation:
- success - the operation is believed to have completed. This may be accompanied by a resource representation conveying the contents of a served resource. A success response is not defined for the create resource operation. See instead created.
- not permitted
- unknown requester
- unknown error - reserved for error conditions that arise that are not anticipated by the specification
Logical Resource Organization
JSON-LD Context and Vocabulary
Resource Identification
Define how resources are identified and addressed within the LWS Protocol, including URI schemes, resource naming conventions, and resolution mechanisms. This section may be moved within another section; e.g. Resource Access
Unstable Features
The features described in this section are being drafted to ground discussions and may be removed if there is:
- Lack of consensus to include them, or
- Lack of implementation of those features
Profile Negotiation on Resources
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).
Notifications
Define notification mechanisms that allow clients to be informed of changes to resources, including subscription models, event formats, and delivery mechanisms.
Inbox
Define inbox resources with specific semantics within LWS, including message posting, retrieval, and management capabilities for asynchronous communication patterns.
Portability Considerations
Describe considerations for ensuring LWS implementations can work across different platforms, environments, and storage backends while maintaining interoperability - and provide affordances to enable change in storage providers