-
Notifications
You must be signed in to change notification settings - Fork 96
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.
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
solid:main
Choose a base branch
from
pdsinterop:feat/intent-handover
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+272
−0
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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> | ||
| <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&solidWebId=https://example.com/profile/card#me</code></pre> | ||
| <p>Examples using query parameters:</p> | ||
| <pre><code>https://target.app/?intent=login&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&solidResource=https://storage.example.com/resource.ttl</code></pre> | ||
| <p>Examples using query parameters:</p> | ||
| <pre><code>https://target.app/?intent[]=open&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&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&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> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
|
|
||
| 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. | ||
|
|
||
| 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 | | | ||
| | `solidWebId` | A Solid compatible WebID URI | login | | ||
| | `solidIdp` | A Solid Identity Provider URI | login | | ||
| | `solidStorage` | A Solid Storage URI | open | | ||
| | `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. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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?