Summary

Add optional --lws-mode flag to support W3C Linked Web Storage (LWS) protocol semantics alongside the current Solid Protocol/LDP implementation.

Status: 📋 Draft/Exploratory - LWS spec is in early stages (PR #37 just merged Jan 2026)
Priority: Low (monitor ecosystem first)
Related: w3c/lws-protocol#37

Background

What is LWS?

The W3C Linked Web Storage protocol suite defines CRUD operations with different conventions than Solid/LDP:

• POST for creation (server-assigned URIs with Slug hints)
• PUT for updates only (not creation)
• Link headers for metadata (removes slash semantics for containers)
• Mandatory ETag concurrency control
• JSON Merge Patch for metadata updates (via separate linkset resources)

Current State: LDP/Solid

JSS implements Solid Protocol conventions based on LDP:

• ✅ PUT creates or updates resources
• ✅ Trailing slash indicates containers
• ✅ POST to containers with Slug support
• ✅ ETag-based If-Match/If-None-Match
• ✅ N3 Patch and SPARQL Update for RDF modifications

Key Differences

Proposed Implementation

Configuration Flag

# LWS mode
jss start --lws-mode

# Solid/LDP mode (default, current behavior)
jss start

Code Changes Required

1. PUT Handler Split (src/handlers/resource.js)

Effort: 3 hours

export async function handlePut(request, reply) {
  const lwsMode = request.lwsMode || false;
  
  if (lwsMode) {
    // LWS: PUT only for updates
    const stats = await storage.stat(storagePath);
    if (\!stats) {
      return reply.code(404).send({
        error: 'Use POST to create resources in LWS mode'
      });
    }
  } else {
    // LDP: PUT creates or updates (current)
    const existed = stats \!== null;
  }
}

2. Container Detection Toggle (src/utils/url.js)

Effort: 4 hours

export function isContainer(urlPath, request) {
  if (request?.lwsMode) {
    // LWS: Check Link header for Container type
    const linkHeader = request?.headers?.link || '';
    return linkHeader.includes('ldp#Container');
  } else {
    // LDP: Trailing slash
    return urlPath.endsWith('/');
  }
}

Files affected: src/utils/url.js, src/handlers/resource.js, src/handlers/container.js, src/ldp/headers.js

3. Linkset Metadata Endpoints (new)

Effort: 8 hours

New file: src/handlers/linkset.js

• GET /resource;linkset - Return metadata as JSON
• PATCH /resource;linkset - JSON Merge Patch for user-managed metadata

4. Config Infrastructure

Effort: 2 hours

Add --lws-mode flag to CLI and config system.

5. Testing Matrix

Effort: 12 hours

Duplicate all CRUD tests for LWS mode (223 tests × 2 modes = 446 tests total).

Complexity Assessment

Trade-offs

Pros ✅

• Future-proof if LWS gains adoption
• Universal server supporting both protocols
• Research value for evaluating LWS concepts
• Subdomain isolation - run Solid + LWS pods on same server

Cons ❌

• Test burden - doubles maintenance (446 tests)
• Code complexity - branching logic throughout
• Premature - LWS ecosystem is tiny (no known apps)
• Bug risk - less-used mode more error-prone
• Documentation split - user confusion

Decision Criteria

Do NOT implement until:

• ✅ At least 3 other servers implement LWS
• ✅ At least 5 client apps request LWS support
• ✅ W3C Solid CG shows interest in LWS alignment
• ✅ LWS spec reaches Candidate Recommendation status

Monitor These Signals

• Number of servers implementing LWS
• Client apps using LWS endpoints
• W3C Solid CG discussions about LWS
• LWS spec maturity (currently early draft)

Alternative: Plugin Architecture

Instead of core branching, design protocol adapters:

jss start --protocol=lws      # LWS semantics
jss start --protocol=solid    # LDP semantics (default)
jss start --protocol=s3       # Future: S3-compatible

Benefits:

• Clean core implementation
• Community experimentation
• No test matrix explosion

Current LWS Ecosystem (Jan 2026)

• Servers: Unknown
• Clients: Likely zero
• Spec status: Early draft (PR Login with did:nostr #37 just merged)
• Community: Small W3C working group

Recommendation

Priority: Low - Monitor but don't implement

Timeline:

• Now: Capture this analysis
• Q2 2026: Survey LWS ecosystem adoption
• Q4 2026: Reassess if signals show traction
• 2027+: Implement if ecosystem warrants

Keep focus on:

• ✅ did:key authentication (Support did:key Authentication (LWS10 Spec) #86) - adds capability without breaking changes
• ✅ Solid Protocol improvements - serve existing ecosystem
• ✅ Performance and stability - core value

References

• W3C LWS Protocol PR #37
• W3C LWS Protocol Repo
• LDP Specification
• Solid Protocol