Review and restructure Access Grant Proposal by jeswr · Pull Request #109 · w3c/lws-protocol

jeswr · 2026-03-22T23:41:00Z

@acoburn if you are approving of these changes, I suggest we merge them into your PR ASAP and continue discussion there -- rather than having two threads of discussion on Access Grants.

Summary

This branch restructures the LWS Access Requests and Access Grants specification to properly align with the ODRL Information Model. The flat access object is replaced with a standards-compliant ODRL Policy structure using permission/prohibition/obligation rules, a formal profile vocabulary is defined, and JSON-LD context and framing are specified.

Changes

ODRL Policy Structure (breaking change to data model)

Rule-based access policies: The access object is now a proper ODRL Policy containing permission, prohibition, and obligation arrays. Each rule carries its own action, target, assignee, and constraint — replacing the previous flat structure where these were top-level properties on the policy.
ODRL Policy subclasses: Access requests use odrl:Request; access grants use odrl:Offer. The previous ODRLAccessPolicy type on the access object is replaced with these standard ODRL policy subclass types.
profile property: Every access policy now includes a required profile property (https://www.w3.org/ns/lws#ODRLAccessProfile) per the ODRL profile mechanism.
Singular action per rule: action is now a single string per rule instead of an array on the policy, allowing fine-grained constraint attachment per operation.
Singular target per rule: target is now a single URI per rule instead of an array on the policy.

`hasPurpose` → `purpose` constraint

The non-standard hasPurpose top-level property is removed. Purpose is now expressed as an ODRL constraint using the existing odrl:purpose left operand — consistent with how other conditions (temporal, client, etc.) are expressed.

New vocabulary terms

lws:append action: A new action defined as odrl:includedIn odrl:modify. Granting modify implicitly includes append, but append alone permits only insert-only PATCH operations.
lws:create action: Defined as odrl:includedIn odrl:use. Corresponds to HTTP POST on an LWS container.
lws:resourceType left operand: Renamed from type to avoid collision with rdf:type/JSON-LD @type.
lws:issuer left operand: New constraint for restricting access based on the identity provider that authenticated the agent.
Formal Turtle definitions with rdfs:label, skos:definition, skos:note for all profile-specific terms.

New specification sections

Vocabulary (§3.1): Formal definitions of all profile actions and left operands, including RDF/Turtle.
JSON-LD Context (§3.2): Full context excerpt mapping short-form property names to IRIs.
JSON-LD Frame (§3.3): A JSON-LD 1.1 Frame for deterministic deserialization of access documents.
Policy (§3.4): Normative definition of the Policy object (type, profile, rule arrays).
Rules (§3.5): Properties on Permission/Prohibition/Obligation (action, assignee, target, constraint).
Prohibitions and Obligations (§3.7): New examples showing prohibition (deny a subtree) and obligation (duty) rules.
Groups (§3.8): Support for defining agent groups in access policies using vcard:Group.

Editorial / structural

Added Storage Manager to terminology with a formal definition.
Changed storage manager references to use the <a>storage manager</a> dfn link.
Added JSON-LD11-FRAMING and VCARD-RDF to localBiblio.
Increased maxTocLevel from 2 to 4 to expose the new subsection hierarchy.
Updated all examples throughout the document to use the new rule-based structure.

Copilot

Pull request overview

Restructures the LWS Access Requests / Access Grants specification to align the access object with the ODRL Information Model (Policy + rule arrays), and adds supporting vocabulary + JSON-LD context/framing guidance.

Changes:

Replaces the previous flat access object with an ODRL Policy shape using permission / prohibition / obligation rules and updated examples.
Adds profile vocabulary definitions (actions/left operands/party classes) and introduces JSON-LD Context and JSON-LD Frame sections.
Tightens/clarifies protocol and validation requirements (e.g., POST handling, status codes, notifications).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-22T23:44:58Z

-        requests with an error response. A successful POST operation MUST respond with a
-        <code>Location</code> header set to the URL of the new resource.
+        A POST request MUST include a <code>Content-Type</code> header with a value of
+        <code>application/ld+json</code>.


The protocol text requires Content-Type: application/ld+json on POST. Elsewhere in this repo, LWS defines application/lws+json as its registered media type and treats application/ld+json; profile="https://www.w3.org/ns/lws/v1" as equivalent. Consider allowing application/lws+json and/or requiring the JSON-LD profile parameter, to avoid making Access Requests/Grants incompatible with the LWS media type guidance.

Suggested change

<code>application/ld+json</code>.

<code>application/lws+json</code>, or <code>application/ld+json</code> with a

<code>profile</code> parameter of <code>"https://www.w3.org/ns/lws/v1"</code>.

Copilot · 2026-03-22T23:44:58Z

-          </li>
-        </ul>
+          <p>
+            This property is OPTIONAL, though servers MAY require it.


In the profile intro you say each rule carries its own action, target, assignee, and constraint properties, but later the rule target is described as OPTIONAL. Please reconcile these requirements (either make target required for this profile, or adjust the earlier description to reflect that target may be omitted).

Suggested change

This property is OPTIONAL, though servers MAY require it.

This property is REQUIRED for this profile.

acoburn · 2026-03-23T00:34:02Z

Thanks, @jeswr
The changes here go much further than I would expect. We should discuss. For example, it should be possible to create a profile that isn't based on ODRL, but these changes more or less prevent that and also bring ODRL into the global LWS json ld context, which I am also trying to avoid.

acoburn

All the vocabulary-related text should be moved into separate files (ideally separate PRs)

I like some of these changes, but as a package, this is too much (especially with a request to "merge immediately")

acoburn · 2026-03-23T00:35:10Z

        xref: ["web-platform"],
        group: "lws",
-        maxTocLevel: 2,
+        maxTocLevel: 4,


This was intentionally set at 2

acoburn · 2026-03-23T00:35:55Z

            publisher: "W3C",
            status: "ED",
          },
+          "JSON-LD11-FRAMING": {


Are you sure this isn't present in specref?

acoburn · 2026-03-23T00:36:12Z

+            publisher: "W3C",
+            status: "REC",
+          },
+          "VCARD-RDF": {


Are you sure this isn't present in specref?

acoburn · 2026-03-23T00:37:11Z

          referencing it with a <code>conformsTo</code> property in a Storage Description resource.
        </li>
+        <li>
+          <dfn>Storage Manager</dfn> &mdash; an agent with administrative control over a


This term should be defined in the core spec, not here. Plus we need to align on this terminology in the first place.

acoburn · 2026-03-23T00:38:00Z

-        describes the requested or permitted operations. A profile that describes
-        <a>access requests</a> using ODRL
-        concepts is described in <a href="#odrl-access-policy-profile"></a>.
+        describes the requested or permitted operations. The <code>access</code> object is an


This is problematic. Forcing all access objects to be based on ODRL is too strict

acoburn · 2026-03-23T00:38:44Z

-    "target": ["https://storage.example/projects/"],
-    "hasPurpose": ["https://purpose.example/collaboration"],
-    "constraint": [
+    "type": ["Request"],


Doing this moves the ODRL vocabulary into the global scope of the LWS context, which we definitely should avoid

acoburn · 2026-03-23T00:40:43Z

-    "target": ["https://storage.example/projects/"],
-    "hasPurpose": ["https://purpose.example/collaboration"],
-    "constraint": [
+    "type": ["Offer"],


Similar to the Request type, doing this forces the ODRL namespace to be in global scope

acoburn · 2026-03-23T00:44:18Z

+              Defined by [[!ODRL-VOCAB]].</li>
+            <li><code>modify</code> &mdash; modify an existing resource (HTTP PUT, PATCH).
+              Defined by [[!ODRL-VOCAB]].</li>
+            <li><code>append</code> &mdash; add content to an existing resource without removing


I would avoid append here. ODRL has specifically deprecated that term

acoburn · 2026-03-23T00:45:58Z

+            <li><code>client</code> &mdash; the client identifier for an HTTP request.
+              Defined by this specification.</li>
+            <li><code>mediaType</code> &mdash; the media type of the target HTTP resource.
+              Reuses the <code>as:mediaType</code> term from


I was intentionally avoiding use of AS:mediaType. That decision should be made separate to this, as it affects the core spec

renyuneyun · 2026-03-23T09:38:44Z

(Haven't been able to read the details of this PR due to https://pr-preview.s3.amazonaws.com/w3c/lws-protocol/pull/109.html not rendering. But here are some points by reading the textual summary.)

I feel supporting a full ODRL policy as (any form of) recommendations (or any special roles) to access requests to LWS is not a good idea, at least until some additional break throughs of ODRL comes into reality (at least, the formal semantics and general reasoner; some additional things are needed as well), due to complication and poor user experience for the resource owner (and maybe app developers too).

(My stance: I fully support allowing expressing complex policies in any custom forms, including ODRL, DToU, SAI, etc. I'm raising a concern of putting a complicated policy language as a recommendation at this moment without fully evaluating its effects.)

Two main points:

An ODRL policy can be very complicated with nested fields, and thus the server needs complex mechanisms to handle that. Users would be overwhelmed too, if they need to manually approve that.
There is no existing tool to support automated checking / comparison between two ODRL policies (e.g. between a Request and a Policy), unless significant simplications are made (please correct me if I'm wrong).

Two more/smaller points:

Much information in ODRL cannot be actionable by LWS server, such as Obligation, Purpose, and Constraint in general. It brings no added value to LWS if they cannot be operationalized.
The ODRL Request class may be a mislead if not properly considered. Representation of request for the ODRL Evaluator odrl#93 illustrates this potential mismatch. As a summary, if we use odrl:Request, we intentionally restrict the Access Request to only be part of the "Access Request resource ==> Access Grant resource" flow; it will not support describing the access information (state of the world) and thus being checked by the Authorization Server. This may or may not be intended.

elf-pavlik · 2026-03-23T11:46:07Z

For the record, former SolidLab has few (8) repos implementing around ODRL

https://github.com/search?q=org%3ASolidLabResearch+odrl&type=repositories

maxleonard · 2026-03-23T17:45:20Z

Question on 'Purpose':
If a purpose is a URI (and there is no space for free-text), it means the content on any purpose resource could change with no indication that this has taken place in the original request.

It is important to be able to keep a signed record of what was displayed to the user. How should system implementers deal with this?

renyuneyun · 2026-04-04T06:18:21Z

If a purpose is a URI (and there is no space for free-text), it means the content on any purpose resource could change with no indication that this has taken place in the original request.

I feel it is expected a stable ontology/vocabulary is used for the purpose field. A well-behaved ontology will have versions embedded in its URL. (To be fair, this relies on trust of people managing the ontology. Though, things like hash and signatures can be used to assist determining who is not trustworthy. I feel this is less an issue in principle -- we all rely on some trusts anyway on the Internet -- DNS, SSL/TLS, platforms, etc.)

The implementor (or some curators) can provide a list of known good ontologies, so the user-facing app can inform the user whether the referenced term is in a well-known ontology or not.

jeswr added 4 commits March 21, 2026 17:39

feat: add append action

c90280f

chore: properly define ODRL profile

759a12c

feat: enhance access policy definitions and examples

1a842ae

feat: add support for group definitions in access requests and grants

74617ca

Copilot AI review requested due to automatic review settings March 22, 2026 23:41

jeswr changed the title ~~PR Description: Review and restructure Access Grant Proposal~~ Review and restructure Access Grant Proposal Mar 22, 2026

Copilot started reviewing on behalf of jeswr March 22, 2026 23:41 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

acoburn requested changes Mar 23, 2026

View reviewed changes

renyuneyun mentioned this pull request Apr 4, 2026

Add editors draft for LWS Access Requests and Access Grants #106

Merged

jeswr closed this May 18, 2026

	<code>application/ld+json</code>.
	<code>application/lws+json</code>, or <code>application/ld+json</code> with a
	<code>profile</code> parameter of <code>"https://www.w3.org/ns/lws/v1"</code>.

	This property is OPTIONAL, though servers MAY require it.
	This property is REQUIRED for this profile.

Uh oh!

Conversation

jeswr commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

ODRL Policy Structure (breaking change to data model)

hasPurpose → purpose constraint

New vocabulary terms

New specification sections

Editorial / structural

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

acoburn commented Mar 23, 2026

Uh oh!

acoburn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

renyuneyun commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elf-pavlik commented Mar 23, 2026

Uh oh!

maxleonard commented Mar 23, 2026

Uh oh!

renyuneyun commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jeswr commented Mar 22, 2026 •

edited

Loading

`hasPurpose` → `purpose` constraint

renyuneyun commented Mar 23, 2026 •

edited

Loading