AI-generated Key Takeaways
-
A statement list is a JSON-encoded file or snippet used to declare relationships between digital assets like websites and apps.
-
The statement list consists of a JSON array of one or more statements, each containing a
relation
array and atarget
object. -
Targets can be either websites, specified by a
web
namespace andsite
URI, or Android apps, specified by anandroid_app
namespace,package_name
, andsha256_cert_fingerprints
. -
Optional
relation_extensions
can be added to a statement to provide more detailed information on the permissions and associations granted. -
For situations requiring many statements or statements from different principals,
include
statements can point to a central file containing the statements, with a maximum of 10 included files allowed.
A statement list is a JSON-encoded file or snippet in a well-known location.
Location of statement list
See Creating a statement list to learn where this list should be stored.
Syntax
The statement list or snippet consists of a JSON array of one or more website or app statements as JSON objects. These statements can be in any order. Here is the general syntax:
[ { "relation": ["relation_string"], "target": {target_object} } , ... ]
- relation
- An array of one or more strings that describe the relation being declared about the target. See the list of defined relation strings. Example:
delegate_permission/common.handle_all_urls
- target
- The target asset to whom this statement applies. Available target types:
- relation_extensions (optional)
-
You can add an optional
relation_extensions
field to a statement to provide more information on the permissions and associations you want to grant. This field should be an object where each key is a relation string, and the value is an object containing the extensions for that relation. Clients that request these statements need to be updated to respect these fields.For example,
relation_extensions
for thedelegate_permission/common.handle_all_urls
relation may look like:{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.app", "sha256_cert_fingerprints": ["..."] }, "relation_extensions": { "delegate_permission/common.handle_all_urls": {...} } }
The DAL API supports returning relation_extensions in API calls when the
return_relation_extensions=true
parameter is set in the request.
Example statement list
Here is an example website statement list that contains statements about both websites and apps: http://example.digitalassetlinks.org/.well-known/assetlinks.json
Scaling to dozens of statements or more
In some cases, a principal might want to make many different statements about different targets, or there might be a need to issue statements from different principals to the same set of targets. For example, a website may be available on many different per-country Top Level Domains, and all of them may want to make a statement about the same mobile app.
For these situations, include statements can be helpful. Using this mechanism, you can set up pointers from many different principals to one central location, which defines statements for all of the principals.
For example, you might decide that the central location should be `https://example.com/includedstatements.json`. This file can be configured to contain the same content as in the examples above.
To set up a pointer from a web site to the include file, change `https://example.com/.well-known/assetlinks.json` to:
[{ "include": "https://example.com/includedstatements.json" }]
To set up a pointer from an Android app to the include file, change `res/values/strings.xml` to:
<resources> ... <string name="asset_statements"> [{ \"include\": \"https://example.com/includedstatements.json\" }] </string> </resources>
More Information
There is a more detailed explanation of the statement list format and the underlying concepts in our specification document.