# Document-Policy (/en/docs/web-security/policies/document-policy)



Document-Policy configures behavior and feature constraints for a single document
through named configuration points, for example enabling the JS Self-Profiling API
with `js-profiling`. Unlike [Permissions-Policy](/en/docs/web-security/policies/permissions-policy), it is not delegated to
subframes in the same way, so it is a per-document set of guardrails.

<Callout type="warn" title="Experimental">
  Document-Policy is a WICG Community Group draft, not a W3C standard, and is implemented only in Chromium, where most configuration points sit behind flags; only `js-profiling` is enabled by default. The set of configuration points is implementation-defined and can change, so do not rely on a fixed directive list.
</Callout>

The usable configuration today enables the JS Self-Profiling API:

```http
Document-Policy: js-profiling
```

## How Document-Policy works [#how-document-policy-works]

The header is a structured-field dictionary of configuration points. Each point has
a typed value, a boolean (`?0` off, `?1` on), an integer, a float, or an enum, and
each point governs one behavior of the document. Which points exist is defined by
the browser, not a fixed standard registry.

## How to configure Document-Policy [#how-to-configure-document-policy]

| Configuration point                       | Status          | What it does                                                                                   |
| ----------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------- |
| `js-profiling`                            | 🧪 Experimental | Enables the JS Self-Profiling API. The one configuration point enabled by default in Chromium. |
| `include-js-call-stacks-in-crash-reports` | 🧪 Experimental | Gates whether crash reports include JavaScript call stacks.                                    |

Document-Policy is a WICG draft, implemented only in Chromium, and most of its
configuration points sit behind flags. The two points above are the ones worth
knowing today; treat any longer list as unstable, and confirm a point works in your
target browsers before relying on it.

## Report-only mode [#report-only-mode]

```http
Reporting-Endpoints: doc-endpoint="https://<Endpoint-ID>.report.centralcsp.com"
```

```http
Document-Policy-Report-Only: js-profiling;report-to=doc-endpoint
```

Each point can carry a `report-to` parameter; `*;report-to=endpoint` sets a default
endpoint for all points, and `report-to=none` disables reporting for a point. The
draft defines `Document-Policy-Report-Only`, but end-to-end report delivery in
Chromium is not confirmed, so verify that reports actually arrive before you build
on them.

## What it protects against [#what-it-protects-against]

Today, less than the name suggests. The two usable configuration points gate
diagnostics rather than block attacks: `js-profiling` controls whether a document
can profile its own JavaScript, and `include-js-call-stacks-in-crash-reports`
controls whether crash reports carry call stacks. The value of the header is opting
into those capabilities deliberately, per document.

## Insecure configurations to avoid [#insecure-configurations-to-avoid]

Leaving a known-risky configuration point unconstrained defeats the purpose, and, as
with any reporting feature, pointing `report-to` at a host you do not control leaks
report data. Constrain the points you care about explicitly rather than assuming a
safe default.

## Known bypasses and limitations [#known-bypasses-and-limitations]

There is no normative registry of configuration points, support is Chromium-only,
and the policy is not delegated to subframes the way Permissions-Policy is, so it
governs the document it is set on rather than a whole frame tree.

## Risks [#risks]

Because the feature set is unstable, a point you depend on may change or be removed
between browser versions. Keep constraints in Report-Only where you can, and watch
the reports before enforcing.

## Recommendation [#recommendation]

```http
Document-Policy: js-profiling
```

Treat Document-Policy as experimental. Adopt only the two configuration points that
work in Chromium today, `js-profiling` and
`include-js-call-stacks-in-crash-reports`, and only behind testing in your target
browsers. Prefer `Document-Policy-Report-Only` where it is available; the draft
defines it, but end-to-end delivery in Chromium is unconfirmed, so confirm reports
arrive before relying on them.

## Reporting [#reporting]

A per-point `report-to` parameter routes that point's violations to a named
endpoint, and the browser emits the
[document-policy-violation report](/en/docs/web-security/reporting-api/reports/document-policy-violation).
One related point, `include-js-call-stacks-in-crash-reports`, enriches the
[crash report](/en/docs/web-security/reporting-api/reports/crash) with a JS stack, as covered in
[browser crash and unresponsive reports](/en/blog/browser-crash-reports). CentralCSP
collects the [stream](/en/docs/platform/monitoring/document-policy).

## Browser support [#browser-support]

Chromium-based browsers only; experimental, with no normative registry of
configuration points.

## See also [#see-also]

* [document-policy-violation report](/en/docs/web-security/reporting-api/reports/document-policy-violation)
* [Document-Policy explained (guide)](/en/blog/document-policy-explained)
* [crash report](/en/docs/web-security/reporting-api/reports/crash)
* [Reporting-Endpoints header](/en/docs/web-security/reporting-api/headers/reporting-endpoints)
* [Document-Policy monitoring in CentralCSP](/en/docs/platform/monitoring/document-policy)

## Sources [#sources]

* [WICG, Document Policy](https://wicg.github.io/document-policy/)