Application Capability

People choose which applications to use on their resources. When a resource is stored independently of applications, neither the person nor software acting on their behalf can reliably find out which applications can open, edit, annotate, transform, or search it. They also cannot learn what those applications require from the environment, or how to hand the resource over to them. This knowledge is either hard-coded per application or mediated by platform-specific stores and registries.

AI agents assisting users face the same problem. To act on a resource with an application, an agent needs a structured account of what the application can do and how to trigger it, without driving the human interface and without requiring the application to be loaded first.

The problem is also not specific to web applications. Desktop applications and Progressive Web Apps handle resources and register invocation handlers. Their capabilities are described in platform-specific manifests that other parties cannot discover or process uniformly.

• An Application publishes one authoritative, machine-readable description of its capabilities and requirements at a dereferenceable IRI.
• Any Consumer, such as a server, web user agent, application, catalogue, or agent, discovers the description and matches capabilities to a resource and a task.
• A Consumer constructs an invocation IRI from a declared URI Template, so that a user can act on a resource with an application of their choice.
• A server reviews an application's declared requirements, such as Content Security Policy directives, and makes informed authorisation decisions.
• Human-facing and machine-facing use share one declaration. An agent selects a capability from the same description a catalogue or user agent presents to a person, so the two surfaces cannot drift apart.
• The description is independent of how the application is built or deployed. Web applications, Progressive Web Apps, and desktop applications can publish or embed descriptions.
• All of the above works without central registries or prior coordination between the parties.

• Script-level tool calling between an agent and a loaded application.
• Defining or replacing web user agent permission models, Content Security Policy, or access control enforcement.
• Describing user-activated operations or UI events within a running application.
• Operating a registry of applications. Catalogues can be built from published descriptions.
• Authentication. For example, the login invocation property is a hint about who to authenticate as, and the application remains responsible for authenticating the user.

An application publishes an Application Capability Description, a JSON-LD document discoverable from the application IRI (see Discovery). The description declares Capabilities, the actions the application can perform together with their matching criteria. Each capability links to Invocations. An invocation is typically a URI Template whose variables are bound to properties with defined semantics (see Invocation Properties). The description also declares Requirements, such as Content Security Policy directives annotated with their purpose. It can further declare Policies about the application's own conduct. Notifications let the application's needs be reviewed by the server hosting a resource. A description can also be embedded in host formats so that existing application metadata can carry it. Examples include a Web Application Manifest and a Web Extension manifest (see Embedded Descriptions).

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/",
  "capability": {
    "id": "#capability-open",
    "type": "Capability",
    "action": "odrl:display",
    "invocation": {
      "id": "#invoke-open",
      "type": "UriTemplateInvocation",
      "template": "#open={open}",
      "mapping": [{ "variable": "open", "property": "ac:open" }]
    }
  }
}

• Web Application Manifest is scoped to installed applications mediated by the browser or operating system, not to applications acting on third-party resources.
• registerProtocolHandler requires prior browser registration and named schemes rather than arbitrary https: IRIs.
• Hydra Core Vocabulary describes HTTP API operations. This specification reuses its template and mapping terms by aliasing and subclassing, and adds capabilities, requirements, policies, and notifications.
• WebMCP registers script-defined tools imperatively and requires the application to be loaded in the browser.

The Introduction lists the related efforts in full.

dokieli, a clientside editor for decentralised article publishing, annotations, and social interactions, implements features across this specification. It has a capability description in JSON-LD (curl -H'Accept: application/ld+json' https://dokie.li/) and in HTML+RDFa. An independent Application Capability validator checks a page's capability description against a SHACL shape for the vocabulary. Other implementers have expressed interest. Feedback from communities working on agent and application interoperability is particularly welcome. Application, Security, Privacy, Accessibility, and Internationalisation are addressed in Considerations. These include a Threat Model and the completed Security and Privacy Review and Societal Impact Review.

This section is non-normative.

The Application Capability specification defines the following terms. These terms are referenced throughout this specification.

Application

A web application that operates on resources identified by IRIs. An application can be deployed at a fixed origin, embedded in markup-based host languages, or as a Web Extension. An application could act as a Sender, a Consumer, or both.

Sender

An implementation that publishes and, where applicable, delivers an Application Capability Description to a Receiver. Typically an Application making its identity, capabilities, and requirements known.

Receiver

An implementation that accepts and processes capability descriptions or notifications referencing them. Typically an HTTP server that hosts resources, hosts an inbox, reviews declared requirements, and serves Content Security Policy headers accordingly to a Sender or a Consumer.

Consumer

An implementation that reads and processes an Application Capability Description, obtained directly from the Application's IRI or from a Receiver, in order to discover capabilities, prepare invocations, or inform authorisation decisions.

Capability

A declared affordance of an Application: an action that can be triggered by an invocation.

Invocation

The act of triggering an Application to perform processes, for example by navigating to a URI constructed from a URI Template. For invocations based on URI Templates, an invocation covers only the URL-loading step. Subsequent user-activated operations or UI events within the application are out of scope, even though the capabilities do express these affordances.

The following prefixes and namespaces are used in this specification.

This specification uses JSON-LD [JSON-LD11] as the preferred data format, and https://www.w3.org/ns/ac.jsonld as a URI for the JSON-LD context and as a value of the profile parameter used for content negotiation.

{
  "@context": {
    "@version": 1.1,
    "@protected": true,
    "ac":      "https://www.w3.org/ns/ac#",
    "as":      "https://www.w3.org/ns/activitystreams#",
    "dpv":     "https://w3id.org/dpv#",
    "hydra":   "http://www.w3.org/ns/hydra/core#",
    "ldp":     "http://www.w3.org/ns/ldp#",
    "oa":      "http://www.w3.org/ns/oa#",
    "odrl":    "http://www.w3.org/ns/odrl/2/",
    "id":   "@id",
    "type": "@type",
    "Accept": "as:Accept",
    "accept": "ac:accept",
    "action": {"@id": "ac:action", "@type": "@id"},
    "actor": {"@id": "as:actor", "@type": "@id"},
    "browserPermission": "ac:browserPermission",
    "Capability": "ac:Capability",
    "capability": {"@id": "ac:capability", "@type": "@id"},
    "cspDirective": "ac:cspDirective",
    "destination": {"@id": "ac:destination", "@type": "@id"},
    "hasPurpose": {"@id": "dpv:hasPurpose", "@type": "@id"},
    "inbox": {"@id": "ldp:inbox", "@type": "@id"},
    "Invocation": "ac:Invocation",
    "invocation": {"@id": "ac:invocation", "@type": "@id"},
    "issuedPolicy": {"@id": "odrl:issuedPolicy", "@type": "@id"},
    "login": {"@id": "ac:login", "@type": "@id"},
    "mapping": "hydra:mapping",
    "object": {"@id": "as:object", "@type": "@id"},
    "open": {"@id": "ac:open", "@type": "@id"},
    "output": "ac:output",
    "property": {"@id": "hydra:property", "@type": "@id"},
    "proxy": {"@id": "ac:proxy", "@type": "@id"},
    "Reject": "as:Reject",
    "Request": "ac:Request",
    "Requirement": "ac:Requirement",
    "requirement": {"@id": "ac:requirement", "@type": "@id"},
    "resourceType": {"@id": "ac:resourceType", "@type": "@id"},
    "search": "ac:search",
    "selector": {"@id": "oa:hasSelector", "@type": "@id"},
    "state": {"@id": "oa:hasState", "@type": "@id"},
    "shape": {"@id": "ac:shape", "@type": "@id"},
    "summary": "as:summary",
    "template": "hydra:template",
    "UriTemplateInvocation": "ac:UriTemplateInvocation",
    "variable": "hydra:variable"
  }
}

When this context is combined with other JSON-LD contexts, for example ActivityStreams in Request Notifications, it is listed last so that its term definitions apply.

This context does not define a term for typing the application itself. A capability description subject can carry any type from its host vocabulary (for example as:Application, an OAuth client, a doap:Project, or a Web of Things Thing) or none at all. See Capability Description.

The ac vocabulary defines the following classes and properties. Terms mapped to other vocabularies, such as as, hydra, and ldp, retain the semantics of their defining specifications.

All assertions, diagrams, examples, and notes are non-normative, as are all sections explicitly marked non-normative. Everything else is normative.

The key words “MUST”, “MUST NOT”, “SHOULD”, and “MAY” are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The key words "strongly encouraged", "strongly discouraged", "encouraged", "discouraged", "can", "cannot", "could", "could not", "might", and "might not" are used for non-normative content.

The Application Capability specification identifies the following Specification Category to distinguish the types of conformance: content/data (the capability description format), notation/syntax (the URI Template invocation syntax), and protocol (the discovery and notification interactions between Senders, Receivers, and Consumers).

The Application Capability specification identifies the following Classes of Products for conforming implementations.

A single implementation can fulfil more than one role simultaneously.

Capability Description

The structured document describing a web application's capabilities and requirements.

Receiver

An implementation (typically a responding agent such as a server) that accepts HTTP requests to provide a representation of a Capability Description. Receivers also accept notifications to their inbox about capability descriptions so that the needs of an application can be reviewed and processed, such as applying CSP headers or addressing authorisation needs.

Consumer

An implementation that reads and processes a Capability Description in order to discover application's capabilities and requirements, construct invocation instructions, or surface other application affordances.

Sender

An implementation that delivers a Capability Description to a Receiver's inbox.

In this specification, interoperability occurs between the Classes of Products defined by this specification: Consumer–CapabilityDescription, Consumer–Receiver, and Sender–Receiver.

Consumer–Capability Description interoperability

Interoperability of implementations for Consumer and Capability Description is tested by evaluating the description's conformance to the data model and processing of descriptions.

Consumer–Receiver interoperability

Interoperability of implementations for Consumer and Receiver is tested by evaluating an implementation's ability to request and respond to HTTP messages.

Sender–Receiver interoperability

Interoperability of implementations for Sender and Receiver is tested by evaluating an implementation's ability to request and respond to HTTP messages.

This document can be subdivided into the following modules:

• Discovery together with the Data Model
• Notifications

The following application-level properties are defined by this specification for describing an application.

capability

Links the application to one or more Capability declarations.

requirement

Links the application to one or more Requirement declarations.

inbox

The IRI of an inbox to which notifications concerning the application can be delivered, such as the outcome of a requirements review. Applications that wish to receive such notifications can publish this property [LDN].

issuedPolicy

Links the application, as an odrl:Party, to a policy, inline or referenced by IRI, it asserts about its own conduct, e.g., rules over data it processes or defaults it applies to resources it creates [ODRL-MODEL]. Issuing a policy grants no privileges.

These properties can be attached to any resource identifying an application. The Application type is not required for conformance. Consumers process these properties by subject, consistent with Discovery, which targets the application as the subject of these statements. See Embedded Descriptions for usage alongside other vocabularies and within non-RDF formats.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#i",
  "type": "ac:Application",
  "as:name": "Example App",
  "inbox": "https://app.example/inbox/",
  "capability": [
    "https://app.example/#capability-view",
    "https://app.example/#capability-edit",
    "https://app.example/#capability-transform-html"
  ],
  "requirement": [
    "https://app.example/#requirement-scripts",
    "https://app.example/#requirement-styles",
    "https://app.example/#requirement-connect",
    "https://app.example/#requirement-notifications"
  ],
  "issuedPolicy": "https://app.example/#policy-conduct"
}

A Capability is a resource of type Capability that declares one action an application can perform, the media types (if any) the action applies to, and how to invoke it.

Because capabilities are identified by IRIs, they can be shared across applications. An application's capability description can reference a capability IRI published elsewhere (for example, a well-known capability defined by a community or standard) rather than defining its own. Multiple applications linking to the same capability IRI signal that they support the same action under the same terms.

accept

Zero or more media types [IANA-MEDIA-TYPES] that this capability accepts as input.

resourceType

Zero or more IRIs identifying the classes of resource (e.g., rdf:type) this capability applies to.

shape

Zero or more IRIs identifying shapes (e.g., SHACL) for a resource that this capability applies to. The interpretation of a shape is bound to the capability's action: for a display or edit action the shape describes the accepted input, and for a transform action the accepted source. Shape-based matching is stricter than accept or resourceType matching, and Consumers can fall back to the coarser criteria when shape validation is unavailable.

action

The action the application can perform per capability. Each capability declares an action. Recommended practice is to use values from a controlled and shared vocabulary (such as ODRL actions). An application that affords multiple actions declares multiple capabilities, which can share an invocation by reference.

invocation

Links the capability to one or more invocations describing how to trigger it.

destination

The IRI to deliver or save the result to. Used when the action produces an output.

output

Zero or more media types of the result produced by the action. An application that can produce multiple output formats declares a separate Capability for each format. Consumers match the desired output format against the declared output to select the appropriate Capability, then pass that format as the output invocation variable.

Matching semantics: a capability is matched on a criterion (accept, output, resourceType, shape) only if it declares that criterion. An absent criterion is not a wildcard. A capability that declares none of them is selected by its action. Consumers are encouraged to ignore capabilities whose declared action, accept, or resourceType they do not recognise rather than treat them as errors.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#capability-open",
  "type": "Capability",
  "action": "odrl:display"
}

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#capability-open",
  "type": "Capability",
  "action": "odrl:display",
  "invocation": "https://app.example/#invoke-open"
}

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#capability-view",
  "type": "Capability",
  "accept": ["text/html", "text/markdown"],
  "action": "odrl:display",
  "invocation": "https://app.example/#invoke-open"
}

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#capability-edit",
  "type": "Capability",
  "accept": ["text/html", "text/markdown"],
  "action": "odrl:modify",
  "invocation": "https://app.example/#invoke-open"
}

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#capability-transform",
  "type": "Capability",
  "accept": "text/markdown",
  "action": "odrl:transform",
  "output": "text/html",
  "destination": "https://storage.example/output/",
  "invocation": "https://app.example/#invoke-transform"
}

An Invocation is a resource describing one mechanism by which a capability is triggered. Invocation is an abstract class. Every Invocation is typed with one of its subclasses. This specification defines UriTemplateInvocation. Other invocation kinds can be described by defining additional subclasses of Invocation. This specification does not constrain their form.

A capability can declare multiple invocations. A Consumer selects an invocation according to its own deployment context and not by document order. Consumers are encouraged to ignore invocations of a type they do not recognise rather than treat them as errors.

An application ultimately decides whether to carry out a given invocation and in which order invocations are processed. An error with one invocation could prevent related invocations from being fulfilled.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#invoke-open",
  "type": "UriTemplateInvocation",
  "template": "#open={open}",
  "mapping": [
    {
      "variable": "open",
      "property": "ac:open"
    }
  ]
}

Resolved against application IRI https://app.example/ with
     open = https://data.example/article :

https://app.example/#open=https%3A%2F%2Fdata.example%2Farticle

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#invoke-transform",
  "type": "UriTemplateInvocation",
  "template": "#open={open}&output={output}",
  "mapping": [
    { "variable": "open", "property": "ac:open" },
    { "variable": "output", "property": "ac:output" }
  ]
}

Resolved against application IRI https://app.example/ with
     open   = https://data.example/report.md
     output = text/html :

https://app.example/#open=https%3A%2F%2Fdata.example%2Freport.md&output=text%2Fhtml

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#invoke-selector",
  "type": "UriTemplateInvocation",
  "template": "#selector(type=TextQuoteSelector,prefix={prefix},exact={exact},suffix={suffix})",
  "mapping": [
    { "variable": "prefix", "property": "oa:prefix" },
    { "variable": "exact",  "property": "oa:exact" },
    { "variable": "suffix", "property": "oa:suffix" }
  ]
}

Resolved against application IRI https://app.example/ with
     prefix = "dokieli is an "
     exact  = "open source project"
     suffix = " using open web standards." :

https://app.example/#selector(type=TextQuoteSelector,prefix=dokieli%20is%20an%20,exact=open%20source%20project,suffix=%20using%20open%20web%20standards.)

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#invoke-clip",
  "type": "UriTemplateInvocation",
  "template": "#t={start},{end}",
  "mapping": [
    { "variable": "start", "property": "https://app.example/ns#start" },
    { "variable": "end",   "property": "https://app.example/ns#end" }
  ]
}

Resolved against application IRI https://app.example/ with
     start = 30
     end   = 60 :

https://app.example/#t=30,60

This section defines properties that give invocation variables their meaning. A template variable is a local placeholder. Its meaning comes from the property it is mapped to, whether a property defined here or an application-defined one. A Consumer resolves each variable by its property, not by its name, and can still expand the template with the variables whose property it recognises. Using a property's local name as the variable name, for example {open} for open, is a convention for readability.

The properties defined here parameterise the IRI used to invoke an application. They do not represent user-activated operations or UI events within the running application. Those are the concern of the user agent and the relevant browser specifications.

Each entry below is an invocation property, shown by its conventional variable name. The name is what you use in a template and mapping. The property it denotes is what a Consumer resolves.

open

The IRI of a resource to open. The application renders, displays, or edits the identified resource.

selector

A selector identifying a segment of the resource to focus on, as defined in [SELECTORS-STATES]. Its value is carried in functional form as selector(…), whose fields (for example oa:exact, oa:prefix, oa:suffix) become the template variables.

state

A state identifying a specific version or representation of the resource, as defined in [SELECTORS-STATES]. Its value is carried in functional form as state(…).

search

A query or search expression submitted to the application. The format and interpretation are application-defined: the value can be a freetext string, a structured query, or any other expression the application understands.

output

The media type of the desired output. Used when invoking a transform capability: its value ought to match the output declared by the selected Capability. A Consumer that wants HTML output selects the capability declaring output: text/html and passes output=text/html in the invocation IRI.

login

The IRI of a user profile (e.g. a WebID) identifying who to authenticate as. This is a hint, not authentication: the application remains responsible for authenticating the user.

proxy

The URL of a proxy through which the application is intended to route network requests. This variable has no effect on its own. When present alongside open or other variables that involve fetching a resource, the application uses the proxy URL for those requests.

Applications can use properties beyond those defined here, referenced by their own variable names, as described in Invocation Extension.

A requirement is a resource of type Requirement that declares one environmental requirement an application has: a CSP directive the host server ought to include, or a browser permission the application can request at runtime. Where a Capability declares what an application can do, a Requirement declares what the environment needs to provide for the application to function. An application links to one or more Requirement declarations via requirement. Declaring requirements as discrete resources allows each requirement to carry its own purpose annotation and to be individually identified and referenced.

Application requirements serve two roles in this specification. As declarative self-description, they are readable by any Consumer: a catalogue ranking applications by permission footprint, a user agent presenting requirements to a user before invocation, or an authorisation agent reviewing access. As protocol input, they are delivered by a Sender to a Receiver, which reviews and acts on them by applying CSP headers or addressing declared authorisation needs. This active use is described in the Notifications section. The two roles are independent: a Consumer can read and act on declared requirements without any Sender–Receiver exchange having taken place.

Requirements are independent of the invocation mechanism: a Consumer evaluates them before invoking, whichever invocation it selects. Consumers are encouraged to ignore requirement properties they do not recognise rather than treat them as errors.

cspDirective

One or more CSP directives (CSP Level 3 syntax) that the host server ought to include with responses of resources the application creates, modifies, or opens, so that the content of those resources functions as intended for any consumer of them.

browserPermission

One or more browser permission names (Permissions API) the application can request at runtime.

hasPurpose

Links to a DPV purpose class expressing why the application needs the declared permissions, supporting transparency and informed review.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#requirement-scripts",
  "type": "Requirement",
  "cspDirective": "script-src 'self' https://app.example/scripts/app.js",
  "hasPurpose": "dpv:ServiceProvision"
}

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#requirement-notifications",
  "type": "Requirement",
  "browserPermission": "notifications",
  "hasPurpose": "dpv:CommunicationManagement"
}

A policy is a resource of type odrl:Policy [ODRL-MODEL] an application issues about its own conduct. Where a Capability declares an affordance the application can perform, a policy declares a self-imposed constraint on exercising it. Both may use the same odrl:action terms. A self-issued permission compels no one, so an issued policy's substance is usually its prohibitions and obligations. An application links to one or more policies via issuedPolicy, as with capability and requirement.

Policies are declarations, not authorisations. A Consumer can compare an application's issued policies against policies issued by other parties, for example, a user's policies of type odrl:Preference, terms the issuer prefers but can renegotiate, discovered from the user's profile via the same issuedPolicy property, and surface discrepancies to the user before invocation, e.g., an action permitted by the application's policy but prohibited by the user's. Locating a user's profile is out of scope. How policies are matched is left to the Consumer, which may apply ODRL conflict-resolution strategies (odrl:conflict). Consumers are encouraged to ignore policy content they do not recognise rather than treat it as an error.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#i",
  "issuedPolicy": {
    "id": "https://app.example/#policy-conduct",
    "type": "odrl:Policy",
    "odrl:prohibition": {
      "odrl:assignee": { "id": "https://app.example/#i" },
      "odrl:action": { "id": "odrl:sell" }
    }
  }
}

This section is non-normative.

The properties defined in Capability Description attach to any resource identifying an application. An application already described by another vocabulary (e.g., Web Application Manifest, Web Extensions manifest, Description of a Project, Activity Vocabulary, schema.org, Web of Things, or OAuth) can therefore carry them on its existing subject without restructuring:

{
  "@context": [
    "https://www.w3.org/ns/solid/oidc-context.jsonld",
    "https://www.w3.org/ns/ac.jsonld"
  ],
  "id": "https://app.example/#i",
  "client_name": "Example App",
  "capability": ["https://app.example/#capability-open"],
  "requirement": ["https://app.example/#requirement-scripts"]
}

A JSON-based format that is not JSON-LD can carry a capability description as a self-contained member under its own key, whose value is a JSON-LD object using this specification's context. Processors of the host format ignore the member, and Consumers extract and process it as JSON-LD.

{
  "name": "Example App",
  "start_url": "/",
  "ac": {
    "@context": "https://www.w3.org/ns/ac.jsonld",
    "id": "https://app.example/#i",
    "capability": ["https://app.example/#capability-open"],
    "requirement": ["https://app.example/#requirement-scripts"]
  }
}

{
  "manifest_version": 3,
  "name": "Example Extension",
  "version": "1.0",
  "ac": {
    "@context": "https://www.w3.org/ns/ac.jsonld",
    "id": "https://app.example/#i",
    "capability": ["https://app.example/#capability-open"],
    "requirement": ["https://app.example/#requirement-scripts"]
  }
}

The ac member name in the non-JSON-LD examples is illustrative: the key under which a host format carries an embedded capability description is declared by that format, not by this specification. Once the member is extracted and processed as JSON-LD, Discovery is unaffected: the application IRI remains the subject of the capability and requirement statements.

An HTML document can carry a capability description in a <script type="application/ld+json"> element, the standard mechanism for embedding JSON-LD in HTML. The element's content is a JSON-LD object using this specification's context, which a Consumer extracts and processes as JSON-LD.

<script type="application/ld+json">
{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#i",
  "capability": ["https://app.example/#capability-open"],
  "requirement": ["https://app.example/#requirement-scripts"]
}
</script>

A Sender uses a request notification to explain its needs to a Receiver. When the request concerns an application, the notification includes the application IRI, the subject of the application's capability description, which the Receiver can dereference (see Discovery). This specification does not constrain which property carries the application IRI. In the examples below it appears as object. When the request pertains to particular resources, the notification includes their IRIs. A request can include or reference one or more objects describing what is requested. This specification does not constrain the vocabulary of those objects.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/ac.jsonld"
  ],
  "type": "Request",
  "actor": "https://agent.example/#i",
  "object": "https://app.example/#i",
  "target": "https://example.org/article"
}

The Receiver's response to a delivery concerns the notification itself: accepting the HTTP request creates the notification in the inbox, independently of any decision about its contents. The Receiver then reviews the stored request, by operator decision or by automated policy, and records the outcome. The Receiver is encouraged to deliver a notification indicating the outcome to an inbox associated with the request: the inbox stated in the request notification if any, otherwise the inbox in the application's capability description. The outcome notification identifies the request notification so that the two can be correlated.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/ac.jsonld"
  ],
  "type": "Accept",
  "actor": "https://example.org/#i",
  "object": "https://example.org/inbox/d3aa37",
  "target": "https://example.org/article",
  "summary": "Requested access modes granted."
}

An application embedded in or injected into an arbitrary HTML document depends on the server hosting that document to issue appropriate Content Security Policy (CSP) headers. Without server cooperation, the browser can block scripts, fetches, or other operations the application requires in order to function. A request can ask a Receiver to review the requirements declared in an application's capability description and act on them, for example by including approved CSP directives in responses served in the context of that application.

A Sender publishes a capability description in which the application links to one or more Requirement declarations via requirement. The Receiver obtains the application IRI, whether at registration time, during policy setup, on first encounter with the application, or from a Request Notification, dereferences the capability description, and reviews the declared requirements as described in Request Notification. A review covers only the requirements the Receiver recognises. When serving responses in the context of that application, the Receiver includes CSP headers reflecting the approved requirements.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#i",
  "type": "ac:Application",
  "inbox": "https://app.example/inbox/",
  "requirement": [
    {
      "id": "https://app.example/#requirement-scripts",
      "type": "Requirement",
      "cspDirective": "script-src 'self' https://app.example/scripts/app.js",
      "hasPurpose": "dpv:ServiceProvision"
    },
    {
      "id": "https://app.example/#requirement-connect",
      "type": "Requirement",
      "cspDirective": "connect-src 'self' https:"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: text/html
Content-Security-Policy: script-src 'self' https://app.example/scripts/app.js;
                         connect-src 'self' https:

A request can express that an agent seeks access to a resource. An access request identifies the agent for whom access is requested, the resource or resources concerned, and the operations desired. This specification does not require a particular authorisation or policy vocabulary for expressing the requested access. The Receiver evaluates the request and enacts the outcome through its own access control mechanism. The representation and enforcement of any resulting authorisation, and the review process itself, are outside the scope of this specification.

A common flow, continuing from Error Response Inbox Discovery: an agent using an application attempts an operation on a resource, receives a 403 response advertising an inbox, and delivers an access request to that inbox describing the access it needs. The review is decoupled from the inbox itself: any application authorised to act on the Receiver's behalf can process stored access requests and enact outcomes.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/ac.jsonld",
    { "acl": "http://www.w3.org/ns/auth/acl#" }
  ],
  "type": "Request",
  "actor": "https://agent.example/#i",
  "target": "https://example.org/article",
  "object": {
    "type": "acl:Authorization",
    "acl:agent": { "id": "https://agent.example/#i" },
    "acl:accessTo": { "id": "https://example.org/article" },
    "acl:mode": [ { "id": "acl:Read" }, { "id": "acl:Write" } ]
  }
}

{
  "@context": "http://www.w3.org/ns/odrl.jsonld",
  "type": "Request",
  "uid": "https://app.example/requests/e3b7",
  "permission": [{
    "assignee": "https://agent.example/#i",
    "target": "https://example.org/article",
    "action": ["read", "modify"],
    "constraint": [{
      "leftOperand": "purpose",
      "operator": "eq",
      "rightOperand": "https://w3id.org/dpv#ServiceProvision"
    }]
  }]
}

An inbox is a resource to which notifications are delivered [LDN]. A target resource advertises its inbox, in the Link header and/or as an ldp:inbox relation in its body, and senders and consumers discover it from the target.

Both an application and a Receiver advertise inboxes, for opposite directions of the same exchange:

• An application advertises an inbox in its capability description, through the inbox property, so that it can receive feedback about its requests, such as the outcome of a Requirements Review.
• A Receiver advertises an inbox on a target resource it controls, in the resource's own description or in an error response, so that it can learn what an application needs from it.

Inbox Discovery

Senders and consumers MUST discover the target's inbox as follows, in order [LDN]:

1. from the Link header with a rel value of http://www.w3.org/ns/ldp#inbox
2. if none is found there, from the response body parsed as JSON-LD [JSON-LD11], where an http://www.w3.org/ns/ldp#inbox relation has the target as subject and the inbox IRI as object.

The Sender then delivers a notification to the inbox, conveying information about its application, including the application IRI. Receipt does not oblige the Receiver to act. A Consumer acting on the Receiver's behalf can dereference the capability description from that IRI to verify it, then the Receiver follows the review process described in Request Notification.

A Consumer that has obtained a Sender's capability description, whether directly from the Sender's IRI or via a Receiver, can use it to prepare invocations independently of whether the Sender–Receiver interaction has taken place.

PUT /article HTTP/1.1
Host: example.org
Content-Type: text/html;charset=utf-8

HTTP/1.1 403 Forbidden
Link: <https://example.org/inbox/>; rel="http://www.w3.org/ns/ldp#inbox"

This section is non-normative.

Applications can use properties beyond those defined in Invocation Properties by declaring a mapping that pairs a template variable with the property that defines its meaning. Consumers that do not recognise a property still expand the template with the variables whose property they do recognise, and receiving applications treat extension values as untrusted input, per the receiver rules in URI Template Invocation.

The following properties illustrate invocation extensions:

diff

The IRI of a resource to compare. It is supplied twice, as the original version then the changed version, and the application renders their difference.

graph

The IRI of an RDF dataset or named graph to load and render.

style

The IRI of a stylesheet to apply when rendering the resource.

view

An application-defined value encoding the UI view in which to open the application, such as which panels are active or the current mode. The encoding and interpretation of this variable are not further specified.

{
  "@context": "https://www.w3.org/ns/ac.jsonld",
  "id": "https://app.example/#invoke-graph",
  "type": "UriTemplateInvocation",
  "template": "#graph={graph}",
  "mapping": [
    {
      "variable": "graph",
      "property": "https://vocab.example/graph"
    }
  ]
}

This section is non-normative.

Applications can state environmental needs beyond those defined in Requirement by including properties from other vocabularies.

This section is non-normative.

Senders are strongly encouraged to declare their permission needs accurately and completely. Understating requirements in order to gain access, or overstating them to acquire unnecessary capabilities, undermines the trust model on which this specification relies.

Senders are encouraged to use permissions granted by a Receiver exclusively in the interests of the user on whose behalf those permissions were granted, consistent with the declared purpose expressed via hasPurpose in the capability description.

Senders are encouraged to maintain stability in the URI Templates declared in their capability descriptions, since Consumers and catalogues can cache and rely on these patterns. Where changes are necessary, Senders could provide a transition period during which both the old and new patterns remain functional.

This section is non-normative.

Capability descriptions are strongly encouraged to be published at a location controlled by the application they identify, so that Consumers and Receivers can rely on the serving IRI as a trust anchor.

An application is identified by its IRI, so the same software deployed at different origins constitutes distinct applications. Each publishes its own capability description at its own origin and is trusted on that basis. There is no cross-origin identity by which one deployment could be trusted on the basis of another.

This section is non-normative.

Privacy is one of the ethical values that underpin the web. To empower people with needs to have strong privacy protections with respect to information flows, implementers as well as developers of specifications are encouraged to consider privacy-related design choices as per W3C Privacy Principles [PRIVACY-PRINCIPLES].

Applications that use the fragment (#) form for invocation parameters, as described in this specification, are encouraged to document this choice explicitly, noting that fragment content is not included in the HTTP request target and so is not disclosed to the application's host through the request. It can still reach others by other paths: script in the loaded application can read it (for example via location.hash), a redirect's Location can inherit it (RFC 9110), and it persists in history, bookmarks, and shared URLs.

Senders are encouraged to apply the principle of data minimisation when publishing capability descriptions, disclosing only the information necessary for discovery, invocation, and policy review by Consumers and Receivers.

An invocation whose observable outcome depends on content that the party supplying a value cannot otherwise read can act as an oracle: by supplying candidate values and observing the result, that party infers the content. Applications are encouraged to limit what an invocation's outcome reveals, noting that the outcome can reach the supplier through side channels such as timing, observable effects, or a browsing context the supplier retains, and not only through a deliberate response. See the Threat Model.

This section is non-normative.

This threat analysis follows the framework of the W3C Threat Model for the Web [THREAT-MODEL-WEB] and draws on terminology from the Privacy Principles. Security Threats are classified by a STRIDE threat type and Privacy Threats by a LINDDUN threat type. Each is assigned a risk level from the RISK Extension to DPV taxonomy [DPV-RISK].

This section is non-normative.

These questions provide an overview of security and privacy considerations for this specification as guided by [SECURITY-PRIVACY-QUESTIONNAIRE].

What information does this feature expose, and for what purposes?

Capability descriptions are public and advertise an application's capabilities, invocation templates, and inbox so Consumers can discover and invoke them. An invocation IRI exposes the variables a Consumer supplies, such as the resource to open, to the receiving application. See the Threat Model.

Do features in your specification expose the minimum amount of information necessary to implement the intended functionality?

Yes. An invocation carries only the variables a Consumer chooses to supply, and the fragment form keeps them from the application's host.

Do the features in your specification expose personal information, personally-identifiable information (PII), or information derived from either?

Not inherently. Variables such as login or open can reference a person or their resources. These are supplied by the Consumer and retrieved under the user's own authorization.

How do the features in your specification deal with sensitive information?

The features do not require sensitive information. Receivers treat any values a Consumer supplies as untrusted input.

Does data exposed by your specification carry related but distinct information that may not be obvious to users?

An invocation IRI can reveal the resource being opened, and in the query form disclose it to the application's host. See the Threat Model.

Do the features in your specification introduce state that persists across browsing sessions?

No.

Do the features in your specification expose information about the underlying platform to origins?

No.

Does this specification allow an origin to send data to the underlying platform?

No.

Do features in this specification enable access to device sensors?

No.

Do features in this specification enable new script execution/loading mechanisms?

No. This specification defines no script execution or loading mechanism. Invocation values are data, treated as untrusted input and validated or sanitised before use.

Do features in this specification allow an origin to access other devices?

No.

Do features in this specification allow an origin some measure of control over a user agent's native UI?

No.

What temporary identifiers do the features in this specification create or expose to the web?

None.

How does this specification distinguish between behavior in first-party and third-party contexts?

It does not distinguish them. An invocation can come from any party, receipt implies no grant, and receivers treat all values as untrusted.

How do the features in this specification work in the context of a browser's Private Browsing or Incognito mode?

No difference. The features introduce no persistent state.

Does this specification have both "Security Considerations" and "Privacy Considerations" sections?

Yes. See Security Considerations, Privacy Considerations, and the Threat Model.

Do features in your specification enable origins to downgrade default security protections?

No. Cross-origin fetching of an invocation target remains subject to CORS [FETCH].

What happens when a document that uses your feature is kept alive in BFCache (instead of getting destroyed) after navigation, and potentially gets reused on future navigations back to the document?

Not applicable.

What happens when a document that uses your feature gets disconnected?

Not applicable.

Does your spec define when and how new kinds of errors should be raised?

No new error types. Receivers are encouraged to fail safe and ignore variables they do not recognise.

Does your feature allow sites to learn about the user's use of assistive technology?

No.

What should this questionnaire have asked?

¯\_(ツ)_/¯

This section is non-normative.

These questions provide an overview of ethical considerations and societal impact as guided by [SOCIETAL-IMPACT-QUESTIONNAIRE].

What kinds of activities do you anticipate your specification becoming a critical part of?

Discovering and choosing applications to act on resources: opening, editing, annotating, transforming, and searching. It can become part of how documents and applications interoperate without prior coordination.

What kinds of activities could your specification become a part of that you are not designing for?

Harvesting capability descriptions to profile applications and their operators, and automated agents invoking applications at scale.

Have you considered whether your use cases are sufficiently diverse?

The use cases centre on document-centric applications. Capabilities for other classes, such as media or non-visual agents, are currently expressible through the extension mechanism. As they become better understood, they can inform the core.

What risks do you see in features of your specification being misused, or used differently from how you intended?

An application can misrepresent its capabilities to attract invocations, and invocation IRIs can be crafted to direct a user or application to attacker-chosen resources. See the Threat Model.

Can users of the Web Platform choose not to use features of your specification?

Yes. Applications work without declaring capabilities, and Consumers can ignore declarations. Receipt of an invocation implies nothing, and a Receiver can ignore it.

What groups of people are excluded from using features of your specification?

Publishing a capability description requires an IRI and web hosting, so those without access to hosting depend on providers. Human-readable names and descriptions are only as multilingual as their publishers make them.

What effect may features of your specification have on minority groups?

Any application can describe its capabilities on equal terms, and discovery does not privilege incumbents. Catalogues built on top of these descriptions can introduce their own selection biases.

How might features of your specification affect individuals' psychological well-being, including stress, social interactions, or susceptibility to compulsive use?

No direct effect is anticipated. Notifications to capability inboxes could be a vector for unwanted contact. See Threat Model mitigations on inbox flooding.

What are the power dynamics at play in implementations of your specification?

Publishers control what they claim, Consumers control what they trust and invoke, and Receivers retain authority over what an invocation does. No party needs permission from a platform or registry to participate.

What points of centralization does your feature bring to the web platform?

None required. Descriptions are self-published and discovered from the resources themselves or via notifications. Catalogues can emerge as aggregation points but are optional.

How does your new technology open up ways in which people might be surveilled?

Query-form invocations disclose the target resource to the application's host, and inboxes observe who sends notifications. The fragment form and the Threat Model mitigations limit this.

To what extent do the features in your specification impact the natural environment?

Minimal. Capability descriptions are small documents, and fragment-form invocation is processed client-side without additional requests to the application's host.

What is the expected lifetime of your specification feature(s)?

The features build on stable web technologies (HTTP, IRI), and the extension mechanism allows evolution without breaking deployed descriptions.

Have you completed the Security & Privacy Self-review Questionnaire?

Yes. See Security and Privacy Review.

This section is non-normative.

This section is non-normative.