Skip to content

first draft for an intent-handover spec #798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ylebre wants to merge 2 commits into
base: main
Choose a base branch
from
+272 −0
Open

first draft for an intent-handover spec #798

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bf02ed0
first draft for an intent-handover spec
ylebre Jul 1, 2026
4577c33
updated paramter names to be more concise
ylebre Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions 2026/intent-handover.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
<h1 id="intent-handover-for-solid-applications">Intent Handover for Solid Applications</h1>
<h2 id="abstract">Abstract</h2>
<p>This specification defines a mechanism that enables one Solid application to convey user intent to another Solid application. A receiving application MAY use any, all, or none of the conveyed information.</p>
<h2 id="status-of-this-document">Status of This Document</h2>
<p>This is a draft proposal intended for discussion within the Solid community. It does not yet define a standard and may change based on implementation experience and community feedback.</p>
<h2 id="introduction">1. Introduction</h2>
<p>Solid applications can redirect users to other Solid applications to continue a workflow. During such transitions, the initiating application may already possess information that could simplify the user’s experience, such as the user’s WebID, Identity Provider (IDP), storage location, or a resource that should be opened.</p>
<p>This specification defines a standardized mechanism for communicating such information between Solid applications.</p>
<p>The mechanism is intentionally non-prescriptive. The receiving application retains complete control over how, or whether, the conveyed information is used.</p>
<h2 id="conformance">2. Conformance</h2>
<p>The key words <strong>MUST</strong>, <strong>MUST NOT</strong>, <strong>SHOULD</strong>, <strong>SHOULD NOT</strong>, and <strong>MAY</strong> in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here.RFC 2119 and RFC 8174.</p>
<h2 id="design-principles">3. Design Principles</h2>
<p>The mechanism defined by this specification follows these principles:</p>
<ul>
<li>The initiating application MAY provide one or more pieces of contextual information.</li>
<li>The receiving application MAY use the provided information.</li>
<li>The receiving application MAY ignore any or all provided information.</li>
<li>The receiving application remains responsible for validating any information before acting upon it.</li>
<li>The mechanism does not require any particular authentication or authorization model.</li>
</ul>
<h2 id="intent-parameters">4. Intent Parameters</h2>
<p>This specification defines intent parameters as either HTTP URL fragment parameters or HTTP URL query parameters. The usage depends on the capabilities of the receiving application.</p>
<p>Receiving applications that run purely in the browser SHOULD use fragment parameters to prevent transmission of information to the server.</p>

@elf-pavlik elf-pavlik Jul 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the initiating application construct url with parameters? If it does how would it decide to use query or fragment? The whole idea of having parameters in a fragment doesn't sound familiar to me. Do you have examples of it being used elsewhere?

@Potherca Potherca Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally, the intent was to only support the fragment #, as that avoid more complexity (like capability discovery).

Concerns were raised that this would not work with server-side apps, which I disagree with.

From my perspective, intent only makes sense for a UI. The UI for a server-side app could easily convert the # to a ? and do a URL reload to trigger the server, without the need for supporting both fragment and query parameters.

Regarding

Do you have examples of it being used elsewhere?

Besides generic patterns of single-page applications (SPA) for things like #q=foo&type=bar&filter=baz, there are various apps and protocol that use fragments with the explicit goal of avoiding parameters from reaching the server. Either because they are secret or because the server would not know what to do with those params.

For instance... (click to toggle details)

  • Excalidraw uses fragment parameters for share URLs: https://excalidraw.com/#json=SvgTAQvEpfAAwYdFqFhy1,kT7-izZXZFSgAIxQ9TctGw

  • Kibana (Elasticsearch dashboard) uses fragment parameters for app state: https://your-kibana-domain:5601/app/discover#/?_g=(refreshInterval:(pause:!t,value:0),time:(from:now-15m,to:now))&_a=(columns:!(message),filters:!())

  • M$ Teams uses fragment parameters for streaming initialization context: https://teams.microsoft.com/_#/?ctx=chat&tenantId=xxxx-xxxx-xxxx

  • OAuth 2.0 Implicit Grant Flow (now deprecated) uses fragments for it's Access Token Response RFC 7111

  • RFC-5147 uses fragments to refer to parts of a text file by character or line position (or range): http://example.com/text.txt#line=10,20

  • RFC-7111 does the same but with by row, column, or cell, for CSV files.

  • vdo.ninja (previously bdo.ninja) uses fragment parameters to hide Stream IDs and Room Names from the server: https://vdo.ninja/?push=cam1#p=secret&token=abc123&key=xyz

  • YouTube video player uses fragment parameters for player instructions: https://www.youtube.com/watch?v=dQw4w9WgXcQ#t=90&autoplay=1&cc_load_policy=1

  • etc.

<p>Receiving applications that run server side and thus require the intent to be transmitted to the server, MUST use query parameters.</p>
<p>An initiating application MAY include any combination of the following parameters. When multiple intent parameters are present, the receiving application MAY use any subset of them. Query parameter values MUST be URL-encoded according to RFC 3986. Examples in this document omit URL encoding for readability.</p>
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Value</th>
<th>Used by intent</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>intent</code></td>
<td>login, open</td>
<td></td>
</tr>
<tr class="even">
<td><code>solidWebId</code></td>
<td>A Solid compatible WebID URI</td>
<td>login</td>
</tr>
<tr class="odd">
<td><code>solidIdp</code></td>
<td>A Solid Identity Provider URI</td>
<td>login</td>
</tr>
<tr class="even">
<td><code>solidStorage</code></td>
<td>A Solid Storage URI</td>
<td>open</td>
</tr>
<tr class="odd">
<td><code>solidResource</code></td>
<td>Resource URI (one or multiple)</td>
<td>open</td>
</tr>
</tbody>
</table>
<h3 id="intent">4.1 Intent</h3>
<p>This parameter signals the intent of the user to the receiving app. Currently two possible values are specified.</p>
<h3 id="login">4.1.1 login</h3>
<p>When this intent is signalled, the receiving application MAY initiate authentication using the supplied values from either <code>solidWebId</code> or <code>solidIdp</code></p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#intent=login&amp;solidWebId=https://example.com/profile/card#me</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?intent=login&amp;solidWebId=https://example.com/profile/card#me</code></pre>
<h3 id="open">4.1.2 open</h3>
<p>When this intent is signalled, the receiving application MAY use the provided values from <code>solidStorage</code> and/or <code>solidResource</code> to start the application with a specific resource. The initiating application can implement ‘open with…’ using this mechanic.</p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#intent[]=open&amp;solidResource=https://storage.example.com/resource.ttl</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?intent[]=open&amp;solidResource=https://storage.example.com/resource.ttl</code></pre>
<h3 id="webid">4.2 WebID</h3>
<p>A WebID identifying the user.</p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#solidWebId=https://example.com/profile/card#me</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?solidWebId=https://example.com/profile/card#me</code></pre>
<p>A receiving application MAY use this value to initiate authentication for the supplied WebID.</p>
<h3 id="identity-provider-idp">4.3 Identity Provider (IDP)</h3>
<p>The URI of an Identity Provider.</p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#solidIdp=https://idp.example.com/</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?solidIdp=https://idp.example.com/</code></pre>
<p>A receiving application MAY use this URI as a suggested Identity Provider for authentication.</p>
<h3 id="storage-uri">4.4 Storage URI</h3>
<p>The URI of a Solid storage location.</p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#solidStorage=https://storage.example.com/</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?solidStorage=https://storage.example.com/</code></pre>
<p>A receiving application MAY use this value as the preferred storage location. For users that have multiple storage locations in their profile information, this parameter conveys which storage location the initiating application intends the receiving application to use.</p>
<h3 id="resource-uri">4.5 Resource URI</h3>
<p>The URI of one or multiple resources. If multiple resources are to be opened, this parameter can be used multiple times.</p>
<p>Examples using fragment parameters:</p>
<pre><code>https://target.app/#solidResource=https://storage.example.com/documents/report.ttl
https://target.app/#solidResource[]=https://storage.example.com/documents/report.ttl&amp;solidResource[]=https://storage.example.com/documents/report-metadata.ttl</code></pre>
<p>Examples using query parameters:</p>
<pre><code>https://target.app/?solidResource=https://storage.example.com/documents/report.ttl
https://target.app/?solidResource[]=https://storage.example.com/documents/report.ttl&amp;solidResource[]=https://storage.example.com/documents/report-metadata.ttl</code></pre>
<p>A receiving application MAY attempt to open, inspect, or otherwise use the referenced resource as appropriate for the application’s functionality.</p>
<h2 id="extensibility">5. Extensibility</h2>
<p>Future versions of this specification MAY define additional intent parameters.</p>
<p>Applications SHOULD ignore parameters they do not recognize unless another specification defines their semantics.</p>
<p>Future versions of this specification may evolve towards a broader audience, as the mechanic as described by this specification is not unique to Solid as an ecosystem.</p>
163 changes: 163 additions & 0 deletions 2026/intent-handover.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# Intent Handover for Solid Applications

## Abstract

This specification defines a mechanism that enables one Solid application to convey user intent to another Solid application. A receiving application MAY use any, all, or none of the conveyed information.

## Status of This Document

This is a draft proposal intended for discussion within the Solid community. It does not yet define a standard and may change based on implementation experience and community feedback.

## 1. Introduction

Solid applications can redirect users to other Solid applications to continue a workflow. During such transitions, the initiating application may already possess information that could simplify the user's experience, such as the user's WebID, Identity Provider (IDP), storage location, or a resource that should be opened.

This specification defines a standardized mechanism for communicating such information between Solid applications.

The mechanism is intentionally non-prescriptive. The receiving application retains complete control over how, or whether, the conveyed information is used.

## 2. Conformance

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here.RFC 2119 and RFC 8174.

## 3. Design Principles

The mechanism defined by this specification follows these principles:

* The initiating application MAY provide one or more pieces of contextual information.
* The receiving application MAY use the provided information.
* The receiving application MAY ignore any or all provided information.
* The receiving application remains responsible for validating any information before acting upon it.
* The mechanism does not require any particular authentication or authorization model.

## 4. Intent Parameters

@uvdsl uvdsl Jul 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see intent parameters in this section that are not covered in https://dokieli.github.io/application-capability/#invocation-variables? I believe them to be covered?

Do you see https://dokieli.github.io/application-capability/#uri-template-invocation as an equivalent way to construct the URI with the intent parameters? Or do you see a blocker there?


This specification defines intent parameters as either HTTP URL fragment parameters or HTTP URL query parameters. The usage depends on the capabilities of the receiving application.

@jg10-mastodon-social jg10-mastodon-social Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: How would an initiating application discover the capabilities of the receiving application?

suggestion: I would prefer to use only query parameters

@Potherca Potherca Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer using only fragment parameters.

As the intent is an instruction for the client-side code and not the server, I think that using a hash # would be more fitting than using query params (as those are meant as instructions for the server).

This would also prevent the WebID (or other values) from being visible server-side (in logs, etc.) which I think is better from a privacy perspective.

@jg10-mastodon-social jg10-mastodon-social Jul 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason I would prefer to use query parameters is that its a standard way of passing values for parameters, whereas fragments identify a specific part of the resource.

How would you handle opening a url that already has a fragment?

@uvdsl uvdsl Jul 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As the intent is an instruction for the client-side code and not the server,

I do see the argument of an SPA not accidentally leaking information on the host server logs.
If however the client has a BFF, I think the information are transmitted to the server-side component anyway for authentication? (but that is on purpose then, so probably fine anyway)
And if the app is fully server rendered, I am unsure whether this would work using only fragments?

That asked, there is indeed prior art to having parameters in the fragment, see W3C REC of Media Fragments URI 1.0 (basic). Maybe worth a look regarding their approach and reasoning.


Receiving applications that run purely in the browser SHOULD use fragment parameters to prevent transmission of information to the server.

Receiving applications that run server side and thus require the intent to be transmitted to the server, MUST use query parameters.

An initiating application MAY include any combination of the following parameters. When multiple intent parameters are present, the receiving application MAY use any subset of them. Query parameter values MUST be URL-encoded according to RFC 3986. Examples in this document omit URL encoding for readability.


| Parameter | Value | Used by intent |
| ---------------------- | ------------------------------ | -------------- |
| `intent` | login, open | |

@jg10-mastodon-social jg10-mastodon-social Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: open would presumably imply login, and the presence of a webId or resource would presumably imply login and/or open with respectively. The intent parameter could therefore be removed/optional unless there are specific future plans for it?

| `solidWebId` | A Solid compatible WebID URI | login |
| `solidIdp` | A Solid Identity Provider URI | login |
| `solidStorage` | A Solid Storage URI | open |

@jg10-mastodon-social jg10-mastodon-social Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: this would presumably be a special case of solidResource, and if needed the fact that it is a storage could be confirmed using https://solidproject.org/TR/protocol#storage-resource

| `solidResource` | Resource URI (one or multiple) | open |


### 4.1 Intent

This parameter signals the intent of the user to the receiving app. Currently two possible values are specified.

### 4.1.1 login

When this intent is signalled, the receiving application MAY initiate authentication using the supplied values from either `solidWebId` or `solidIdp`

Examples using fragment parameters:

```
https://target.app/#intent=login&solidWebId=https://example.com/profile/card#me
```

Examples using query parameters:
```
https://target.app/?intent=login&solidWebId=https://example.com/profile/card#me
```
### 4.1.2 open

When this intent is signalled, the receiving application MAY use the provided values from `solidStorage` and/or `solidResource` to start the application with a specific resource.
The initiating application can implement 'open with...' using this mechanic.

Examples using fragment parameters:

```
https://target.app/#intent[]=open&solidResource=https://storage.example.com/resource.ttl
```

Examples using query parameters:
```
https://target.app/?intent[]=open&solidResource=https://storage.example.com/resource.ttl
```

### 4.2 WebID

A WebID identifying the user.

Examples using fragment parameters:

```
https://target.app/#solidWebId=https://example.com/profile/card#me
```

Examples using query parameters:
```
https://target.app/?solidWebId=https://example.com/profile/card#me
```

A receiving application MAY use this value to initiate authentication for the supplied WebID.

### 4.3 Identity Provider (IDP)

The URI of an Identity Provider.

Examples using fragment parameters:

```
https://target.app/#solidIdp=https://idp.example.com/
```

Examples using query parameters:
```
https://target.app/?solidIdp=https://idp.example.com/
```

A receiving application MAY use this URI as a suggested Identity Provider for authentication.

### 4.4 Storage URI

The URI of a Solid storage location.

Examples using fragment parameters:

```
https://target.app/#solidStorage=https://storage.example.com/
```

Examples using query parameters:
```
https://target.app/?solidStorage=https://storage.example.com/
```

A receiving application MAY use this value as the preferred storage location. For users that have multiple storage locations in their profile information, this parameter conveys which storage location the initiating application intends the receiving application to use.

### 4.5 Resource URI

The URI of one or multiple resources. If multiple resources are to be opened, this parameter can be used multiple times.

Examples using fragment parameters:

```
https://target.app/#solidResource=https://storage.example.com/documents/report.ttl
https://target.app/#solidResource[]=https://storage.example.com/documents/report.ttl&solidResource[]=https://storage.example.com/documents/report-metadata.ttl
```

Examples using query parameters:
```
https://target.app/?solidResource=https://storage.example.com/documents/report.ttl
https://target.app/?solidResource[]=https://storage.example.com/documents/report.ttl&solidResource[]=https://storage.example.com/documents/report-metadata.ttl
```

A receiving application MAY attempt to open, inspect, or otherwise use the referenced resource as appropriate for the application's functionality.

## 5. Extensibility

Future versions of this specification MAY define additional intent parameters.

Applications SHOULD ignore parameters they do not recognize unless another specification defines their semantics.

Future versions of this specification may evolve towards a broader audience, as the mechanic as described by this specification is not unique to Solid as an ecosystem.