Application Capability

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.

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#",
    "ldp":     "http://www.w3.org/ns/ldp#",
    "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"},
    "inbox": {"@id": "ldp:inbox", "@type": "@id"},
    "Invocation": "ac:Invocation",
    "invocation": {"@id": "ac:invocation", "@type": "@id"},
    "login": {"@id": "ac:login", "@type": "@id"},
    "mapping": "ac:mapping",
    "object": {"@id": "as:object", "@type": "@id"},
    "open": {"@id": "ac:open", "@type": "@id"},
    "output": "ac:output",
    "property": {"@id": "ac: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",
    "shape": {"@id": "ac:shape", "@type": "@id"},
    "summary": "as:summary",
    "template": "ac:template",
    "UriTemplateInvocation": "ac:UriTemplateInvocation",
    "variable": "ac: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 and ldp, retain the semantics of their defining specifications.

This section describes the conformance model of the Application Capability specification.

The following properties are defined by this specification for the discovery of an application's capabilities and requirements.

capability

Links the application to one or more Capability declarations.

requirement

Links the application to one or more requirement declarations.

inbox

The IRI of a Linked Data Notifications inbox to which a Receiver can deliver notifications about the outcome of a requirements review. Applications that wish to receive such notifications SHOULD publish this property.

The capability and requirement 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 subject of capability or requirement statements. See Embedding in Other Description Formats 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"
  ]
}

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 (RFC 2046) 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; for a transform action it describes 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 Consumer performing a given match never selects a capability that declares no criterion of that kind. A media-type match ignores capabilities without accept, an output-format match ignores capabilities without output, a resource-type match ignores capabilities without resourceType, and a shape match ignores capabilities without shape. Capabilities that declare none of these criteria are selected by action. Consumers SHOULD 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 MUST ignore invocations of a type they do not recognise.

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}"
}

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}"
}

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

This section defines properties in this vocabulary. Each property's local name is both the key for that property under the JSON-LD context and the canonical variable name in URI template expressions. For example, the ac: vocabulary property whose local name is open appears as the JSON-LD key open and as the URI template variable {open}. Applications SHOULD use these properties when the intended semantics match, so that Consumers can resolve variable meaning by property rather than by string convention alone. For variables not defined here, applications can declare a mapping that pairs the variable name used in the template with the defining property. A Consumer that encounters a variable whose property it does not recognise SHOULD still expand the template with the variables it does recognise.

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.

open

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

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.

Additional invocation variables can be introduced 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.

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.

dpv: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",
  "dpv:hasPurpose": { "id": "dpv:ServiceProvision" }
}

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

This section is non-normative.

Because capability and requirement attach to any resource identifying an application, an application already described by another vocabulary, e.g., Application Manifest, Web Extensions Manifest, Description of a Project, Activity Vocabulary, schema.org, Web of Things, OAuth, can include these properties 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/#this",
  "client_name": "Example App",
  "capability": "https://app.example/#capability-open",
  "requirement": "https://app.example/#requirement-scripts"
}

Description formats that are not JSON-LD can carry a capability description as a self-contained member with their own reference, whose value is a JSON-LD object using this specification's context. Processors of the host format ignore the member; 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/#this",
    "capability": "https://app.example/#capability-open",
    "requirement": "https://app.example/#requirement-scripts"
  }
}

In both cases, Discovery is unaffected: the application IRI remains the subject of the capability and requirement statements.

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. 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",
      "dpv:hasPurpose": { "id": "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"
    }]
  }]
}

When a Sender makes an HTTP request and receives a 4xx response, it can discover the Receiver's inbox from that response and send a notification referencing its capability description. This allows a Sender to inform the Receiver of its access modes, declared CSP directives, browser permissions, and processing purposes in response to a rejected request, rather than waiting for the Receiver to fetch the description independently.

A Receiver that wishes to advertise its inbox in a 4xx response MUST do exactly one of the following:

• Include a Link header with a rel value of http://www.w3.org/ns/ldp#inbox.
• Return a representation whose encoded graph contains a relation of type http://www.w3.org/ns/ldp#inbox, where the subject is the target resource and the object is the inbox IRI.

A Sender that receives a 4xx response SHOULD attempt to discover the inbox: first from the Link header; if no inbox is found there, from the response body parsed as an RDF representation. If an inbox is discovered, the Sender delivers a notification to that inbox conveying its application IRI. The Receiver can then dereference the capability description from that IRI and follow 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 introduce invocation variables beyond those defined in Invocation Variables by declaring a mapping that pairs the variable name used in the template with a property that defines its semantics. Consumers that do not recognise the property still expand the template with the variables they do recognise, and receiving applications treat extension variable values as untrusted input, per the receiver rules in URI Template Invocation.

The following variables illustrate invocation extensions:

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.

state

An application-defined value encoding the UI state in which to open the application, such as which panels are active or the current view 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.

Consumers and Receivers are strongly encouraged to verify that a capability description is served from an IRI consistent with the Sender's declared identity before acting on its contents, in order to mitigate the risk of a third party substituting a fraudulent description.

Senders are strongly encouraged to publish capability descriptions at a location that is under the Sender's control and not publicly writable, so that Consumers and Receivers can rely on the serving IRI as a trust anchor.

Consumers and Receivers are strongly encouraged to fetch capability descriptions only over authenticated, encrypted transport (HTTPS), to mitigate tampering in transit.

Receivers are encouraged to re-fetch capability descriptions periodically and, when a Sender's declared requirements have changed since a prior review was recorded, to treat the change as requiring renewed review rather than continuing to act on the earlier decision.

Senders are strongly encouraged to declare only the minimum CSP directives and browser permissions necessary for their intended function. Overly broad declarations strongly discourage Receiver trust and increase the risk of misuse if permissions are granted.

Receivers are strongly encouraged to treat a capability description as informational input to a review rather than as a grant of permissions. The decision to apply declared CSP directives remains with the Receiver's operator, with human review before first use.

Receiving applications are strongly encouraged to treat all invocation parameters as untrusted input, as required by the receiver rules in URI Template Invocation.

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 transmitted to the server and therefore does not disclose the target resource IRI to the host from which the application is loaded.

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.

This section is non-normative.

This section is non-normative.

This section is non-normative.

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

This section is non-normative.

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

This section is non-normative.

This section describes considerations for applications that publish capability descriptions. These are not normative requirements but reflect the spirit of the trust relationship that this specification establishes between applications, servers, and users.

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 dpv: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.