Reasons for separate rest bindings

[jeswr]

In the 2025_06_09 call there was a request by @uvdsl for provenance for the addition of the REST bindings. These were proposed by @ericprud with the following reasons provided for their addition:

1. factor common operations like "Create" - In LDP, Resources are created by PUT or POST. The abstract functionality gives this a single name, which is then referenced in the bindings (table).
2. hide sensitive Resources - The existence of some Resources (including Containers) may be secret and the HTTP binding can offer the option to respond with 404s instead of 401s/403s (à la Github).
3. dual access - someone might want to offer LWS functionality over e.g. GraphQL, gRPC, þe olde SOAP... It is not expected that we will define non-HTTP bindings at this stage of writing the LWS spec; and it is most likely that this will serve as a 'hook' for external specifications to re-use the LWS document with their own bindings
4. targeted critiques - discussions within the WG or with e.g. IETF over the bindings are confined to a single section of the document
5. Specs, tool documentation, API bindings; lots of things can benefit from having concrete names for the LWS operations

[uvdsl]

Thanks @jeswr for summarising your points.

• I do not oppose defining specific terms for operations, e.g., CRUD.
• But I do oppose having loose ends in the protocol specification.

TLDR - addressing the reasons provided for this separation:

1. Factoring common operations & naming. The goal is valid indeed, but this does not require separate bindings. These operations can be clearly defined and named within a single, cohesive specification that relies on its primary transport, as you state: HTTP.

2. Hiding sensitive Resources (404 vs 401/403). This is an important security consideration for an HTTP implementation. It should be specified directly in the section defining HTTP interactions, rather than being used as a justification to separate the entire operational model from HTTP. The Solid Protocol successfully specifies this behaviour without bindings.

3. Dual access (gRPC, SOAP, etc.). I think this is a problematic justification: It introduces immediate and definite costs (specification complexity, risk to interoperability, fragmented security model) for a speculative and, if realized, detrimental benefit. If the WG's primary goal is an interoperable system, it should not standardize a feature that explicitly enables non-interoperable deployments from day one. Asides, both normative input documents as per charter use HTTP and do not rely on bindings.

4. Targeted critiques: A well-structured single document can also facilitate targeted critiques without fracturing the specification in a way that complicates implementation.

A tightly-coupled specification provides greater clarity, stronger interoperability guarantees, and a more coherent security model. I would urge the group to prioritize concrete benefits over abstract and potentially unbound flexibility.

---

Concerns

The Linked Data Platform (LDP)'s terminology is based on the W3C's Architecture of the World Wide Web and on HTTP (RFC7230, RFC7231, RFC7232). In particular, LDP defines the semantics of HTTP methods on LDP resources, i.e., how HTTP methods relate to (CRUD) operations. I would not oppose the LWS protocol to explain (CRUD) operations on HTTP Resources starting from the operation as opposed to from the HTTP method.

However, I am not convinced that decoupling the abstract operation from the implementation provides tangible benefits that would outweigh the costs. This architectural pattern of separating abstract protocol logic from implementation bindings introduces significant and predictable challenges. It prioritizes hypothetical future flexibility over the immediate, primary goals of a standard: interoperability, clarity for implementers, and a coherent security model.

Take the Eclipse Dataspace Protocol (formerly: International Data Spaces (IDS) Protocol) as an example. It relies heavily on this binding approach. The practical outcomes have been:

• It puts additional burden on the reader to constantly cross-reference between different sections of the protocol when reading about how to actually understand and implement the specification.
• To date, no official binding other than HTTP has been specified, meaning the specification carries the complexity of abstraction without any realized benefit of extensibility.
• And if an additional binding is defined, systems implementing one of the binding are not interoperable with systems implementing the other binding - despite following the same abstract specification.

The cost of the abstraction (in cognitive overhead for every implementer to understand two layers of specification instead of one) is paid by the entire community from day one. The benefit is speculative and, if realized, creates non-interoperable silos, directly harming the network effect the standard aims to create.

This separation is not an isolated technical issue; it introduces a well-known and risky architectural pattern of deferring critical implementation choices (transport protocol, security guarantees, ...) to the implementer. We see a similar pattern with Decentralized Identifiers (DIDs) and their DID methods. The result is a fragmented ecosystem where conformance to the standard does not guarantee interoperability. An application that supports one DID method cannot necessarily resolve or trust a DID from another method; the security guarantees are entirely dependent on the specific method (binding) being used.

Such "flexibility" by design prompted formal academic analysis to diagnose the resulting issues in interoperability [1] and protocol security [2] on standards around DIDs and W3C Verifiable Credentials. Note that the research is not about DIDs or VCs in isolation; it is a diagnosis of the problems created by the flexibility that the specifications allow. One way to allow for such flexibility by design is a binding approach (as seen with DID methods).

Therefore, I argue: If implementing/using standards needs to be addressed with multiple scientific papers on interoperability and security, it seems that this architectural pattern of separation of concerns down to the concrete implementation for the sake of flexibility introduces inherent and significant challenges.

The LWS protocol has an opportunity to learn from these precedents and avoid introducing this class of problems into its own design. I therefore propose to not rely on a binding model and instead to define operations directly and normatively on the HTTP protocol to ensure a single clear path to interoperable implementations.

[1] Christoph H.-J. Braun, Vasil Papanchev, Tobias Käfer: SISSI: An Architecture for Semantic Interoperable Self-Sovereign Identity-based Access Control on the Web. WWW 2023: 3011-3021 [Open Access]
[2] Christoph H.-J. Braun, Ross Horne, Tobias Käfer, Sjouke Mauw: SSI, from Specifications to Protocol? Formally Verify Security! WWW 2024: 1620-1631 [Open Access]

[acoburn]

Thank you @uvdsl for this comprehensive explanation. I would like to approach this from a different angle.

It is very true that LDP and the Solid CG Report are tightly coupled to HTTP.

(From LDP) 4.2.1.1 LDP servers MUST at least be HTTP/1.1 conformant servers

(From Solid) 2.1 Servers MUST conform to HTTP/1.1

This provides a certain simplicity, but it also means that any identifier scheme used must, by definition, be compatible with HTTP methods. In practice, this means that data identifiers are HTTP URLs.

In the April 14 we discussed the issue of whether identifiers should be restricted to only be HTTP(S) URLs. While HTTP(S) URLs will certainly play a key role in LWS, there was general support for not restricting data identifiers to the HTTP(S) scheme. This will allow for other schemes, such as DID, which are becoming more prominent.

In particular, in the context of portability, if we restrict data identifiers to HTTP(S) URLs, then we significantly restrict the mechanisms available for moving from one provider to another. Other, DID-based mechanisms make portability much more possible, but not all of these DID methods have direct mappings to REST, especially those that use distributed ledgers.

The goal of a loose coupling between these core operations and REST is to provide exactly this sort of flexibility while not requiring the overhead of portable identifiers for all implementations. It keeps HTTP(S) and REST at the core of LWS, while also not restricting implementors and future specifications that may build upon LWS, especially those that will use some of the newer DID methods.

The specific example that we don't want to emulate is that the current draft of the OpenID Federation specification, when defining an Entity Identifier, states:

This URL MUST use the https scheme

This automatically excludes all DID-based addressing schemes.

Some of the related use cases/requirements for this include: w3c/lws-ucs#30, w3c/lws-ucs#140

[jacoscaz]

Note

Disclaimer: I unfortunately have not been able to really participate in the group so far and I fully recognise the extent of how uninformed my opinion can be. Take what follows with many grains of salt.

For what it's worth, I completely and wholeheartedly share @uvdsl 's concerns.

The specific example that we don't want to emulate is that the current draft of the OpenID Federation specification, when defining an Entity Identifier, states:

This URL MUST use the https scheme

My perspective as a spec implementor leads me to the opposite conclusion. Constraints and boundaries are a feature, not a bug. They make the difference between specifications that can be grasped within a few hours and specifications that require multi-day explorations of topics one might not be as familiar with and that become much harder to argue for when discussing with non-technical parties. Tight coupling with HTTP is, IMHO, the primary factor behind the success of OAuth2 and OpenID Connect in terms of cross-vendor interoperability.

EDIT: I should add that OAuth2 and OpenID Connect implementations are still nowhere near as interoperable as they ought to be. I've yet to see token validation code that doesn't branch out into dedicated code paths depending on the token's issuer. DIDs would make this a thousand times worse.

Therefore, I argue: If implementing/using standards needs to be addressed with multiple scientific papers on interoperability and security, it seems that this architectural pattern of separation of concerns down to the concrete implementation for the sake of flexibility introduces inherent and significant challenges.

This, 100%. Additional complexity should be introduced only when it becomes necessary in the present and when the additional costs can be demonstrably offset by tangible, practical benefits. I do not see any such benefit in using a binding model with effectively just one binding, that to the HTTP protocol, and with no clear plans for other bindings in the short term.

That said... I understand that whether to limit the protocol to HTTP(s) or not has already been discussed and agreed upon. I'm sorry I have not been in a place to take a more active role in the discussion. I would have voiced my concerns at a more useful time :). I hadn't planned on speaking up but @uvdsl's comment is just too well-written not to.

[uvdsl]

Thanks, @acoburn, for providing this additional perspective! Also, thanks for linking my use case #30. Much appreciated.

(From LDP) 4.2.1.1 LDP servers MUST at least be HTTP/1.1 conformant servers

(From Solid) 2.1 Servers MUST conform to HTTP/1.1

This provides a certain simplicity, but it also means that any identifier scheme used must, by definition, be compatible with HTTP methods. In practice, this means that data identifiers are HTTP URLs.

There is a difference between the identifier scheme and transport protocol when considering DIDs: Consider did:web (DID WEB) as an example.
A resource is identified by did:web:example.org:1234 and thus accessible at https://example.org/1234.
The server is easily able to conform to the outlined specification without the requirement for a binding, and resource identifiers are not restricted to HTTP URLs.

In particular, in the context of portability, if we restrict data identifiers to HTTP(S) URLs, then we significantly restrict the mechanisms available for moving from one provider to another.

I have a different perspective on this: As pointed out by my comment in #30, I do not believe that the choice of transport protocol restricts the movement between service providers of an LWS. In addition, kindly consider the comment by @gibsonf1, outlining a concrete approach for moving between service providers of an LWS without breaking links.

Other, DID-based mechanisms make portability much more possible, but not all of these DID methods have direct mappings to REST, especially those that use distributed ledgers.

This argument conflates the protocol for managing a DID (i.e., the method) with the protocol for accessing an LWS.
On the choice of DID method - having some experience at the intersection of Linked Data and Distributed Ledgers [1,2,3] - I argue that choosing such DID methods that do not have a REST mapping creates a protocol-level lock-in, which is more severe than the lock-in that HTTP URLs are criticized for (see @gibsonf1's solution to HTTP URL portability).
On the protocol for accessing an LWS, this is precisely the issue outlined in my comment above: An application that supports one DID method / binding cannot necessarily resolve or trust a DID from another method / binding - thereby fragmenting the ecosystem and harming interoperability.

The goal of a loose coupling between these core operations and REST is to provide exactly this sort of flexibility while not requiring the overhead of portable identifiers for all implementations. It keeps HTTP(S) and REST at the core of LWS, while also not restricting implementers and future specifications that may build upon LWS, especially those that will use some of the newer DID methods.

Thank you for making your rationale explicit. I believe, however, that this approach does not deliver the intended flexibility and instead creates a contradiction within the scope of the LWS protocol. The argument that loose coupling keeps HTTP "at the core" while allowing flexibility creates a fundamental contradiction. If HTTP is truly core to the LWS protocol, then by definition, a non-HTTP-based interaction (whether via a DID method or another binding) would not be compliant with LWS. Conversely, if the LWS standard does allow non-HTTP bindings to be compliant, then HTTP is no longer really the core: It is just one option among potentially many, even if only the REST binding is defined for now. This leads directly to the mentioned fragmented ecosystem, where two servers can be "LWS compliant" but completely unable to interoperate.

If other specifications want to build on-top of the LWS protocol, they can do so regardless of whether or not the LWS protocol follows a bindings approach - if the core operations are well defined (which I am all in favor).
Then, a system implementing that other on-top specification can call itself "LWS-otherTransportProtocol" compliant but not "LWS" compliant - it implements a different standard after all.

Again, I am not arguing against a specific solution - not arguing against solutions like did:web in particular - I am arguing against ambiguity that leads to loose ends in the protocol specification.

---

[1] Christoph Braun, Tobias Käfer: Verifying the Integrity of Hyperlinked Information Using Linked Data and Smart Contracts. SEMANTiCS 2019: 376-390 [Open Access]
[2] Hendrik Becker, Hung Vu, Anett Katzenbach, Christoph H.-J. Braun, Tobias Käfer: Monetising Resources on a SoLiD Pod Using Blockchain Transactions. ESWC (Satellite Events) 2021: 49-53 [Postprint]
[3] Christoph H.-J. Braun, Janina Traue, Boris Lingl, Tobias Käfer: Documenting the Execution of Semantically Modelled Inter-organisational Workflows on a Distributed Ledger. Blockchain 2021: 280-286 [Preprint]

[melvincarvalho]

@ebremer pointed out this issue yesterday on the SolidOS call. Fascinating discussion, I can see both sides.

Personally, I think the current draft strikes a pragmatic balance. It keeps HTTP as the normative core, while allowing future extensions to explore non-HTTP bindings if real-world demand arises. The two-section approach (abstract ops + REST binding) gives clarity without locking us into unnecessary abstraction.

That said, I do share the concern that we should avoid ambiguity or drift in the spec. As @uvdsl noted, even well-intended flexibility can lead to loose ends if not carefully constrained. Keeping the scope and compliance expectations crystal-clear seems important as the spec evolves.

[acoburn]

@uvdsl would like a proper summary of this discussion before closing this issue

[w3cbot]

This was discussed during the #lws meeting on 26 January 2026.

View the transcript

w3c/lws-protocol#24 Reasons for separate rest bindings (by jeswr)

acoburn: #24, is there more discussion to be have?

uvdsl: I'd like to request a proper summary of the discussion before closing the issue

acoburn: if someone could jump in and assign themselves, that would be great. If we do not have someone by next week, we'll pick someone.

---

[pietercolpaert]

In past informal conversations I expressed that I liked the separation between more high-level state transition descriptions and protocol bindings cfr. the Eclipse Dataspaces Protocol. I however agree with the argumentation from @uvdsl above for LWS specifically.

[acoburn]

I will try to summarize this discussion and describe how this relates to the current state of the draft specification.

• The idea of separate REST bindings emerged from the idea that there could be a simple model to describe the basic operations of LWS: Create, Read, Update, Delete. And those simple definitions could be mapped to a set of REST bindings. This was understood to be slightly more complex, from the perspective of the specification text but would allow for the possibility of creating alternative bindings in some future specification that builds on LWS
• The counter-argument to the first point is that this adds complexity to the specification without a clear justification in terms of both use cases and requirements.

At present, when looking at the draft specification, there are two sections: "Operations", which describes the abstract operations and "REST Bindings", which connects those operations to specific REST operations. This currently aligns with the first point, using separate sections. It is worth noting that the first point was predicated on an assumption that the core operations section would be clear and simple and that any definitions there would not inadvertently bleed into the REST bindings.

My personal opinion is that, at present, those core operations do overstep into REST territory, which undermines the basic goal of the first point and suggests that the counter-argument described in the second point is more relevant here.

Indeed, the REST bindings contain a description of Metadata resources, which the Operations section refers to but does not define. Also, the Operations section describes outcomes for "Create" operations that have more to do with REST semantics than generic responses (e.g., Target Not Found == 404, Not Permitted == 403, Conflict == 409). And there are other possible HTTP responses not included in that list, all of which is potentially confusing.

The two outcomes that I see here are:

1. The specification undergoes some textual editing to clarify the potential confusing areas I mentioned (while keeping the overall separation of operation and REST bindings)
2. We collapse the Operations and REST binding sections into one

My personal opinion (and I mention this as one of the early advocates for a separation of REST bindings): we choose the simple approach and collapse the two sections. This will make for a simpler specification and avoids adding complexity to server requirements that the group has not adopted.

[uvdsl]

Thank you, @acoburn, for the summary and for reconciling the different perspectives.

I strongly support your recommendation to collapse the two sections. This path prioritizes specification clarity and interoperability, and thus addresses the core concerns raised throughout this thread.