Document-Policy

Rendering behavior, resource constraints, and performance characteristics within a page need configurable control beyond binary allow/deny toggles. The HTTP Document-Policy response header provides that control through parametric document-level policies.

Table of Contents

Usage

The Document-Policy header gives servers control over specific document behaviors at the browser level. While Permissions-Policy governs access to browser APIs using a boolean allow/deny model, Document-Policy targets rendering and resource behavior inside the document with configurable parameters. A permissions policy toggles whether a feature is available. A document policy configures how a feature behaves, accepting threshold values and enumerated states.

Policies are declared as a Structured Fields dictionary. Each directive names a behavior and optionally sets a parameter value. Boolean directives use Structured Header boolean syntax. Threshold directives accept decimal or integer values. An optional report-to parameter on each directive names a Reporting API endpoint for violation reports.

Document-Policy: sync-xhr=?0;report-to=perf, js-profiling

sync-xhr illustrates the syntax here. The directive itself sits behind an experimental Chromium flag (see Directives), while js-profiling works without one.

The Document-Policy-Report-Only response header applies the same syntax but reports violations without enforcing them. This allows production monitoring before committing to enforcement.

Document-Policy-Report-Only: sync-xhr=?0;report-to=perf

A report-only directive without a report-to parameter has no effect at all, so a bare Document-Policy-Report-Only header silently does nothing.

For embedded content, the specification defines a negotiation mechanism: the Require-Document-Policy response header sets the minimum policy for nested iframes, the browser sends a Sec-Required-Document-Policy request header on subframe requests, and an embedded document failing to return a compatible Document-Policy is blocked. Individual iframes accept a policy attribute for per-frame constraints. The whole negotiation flow is experimental in Chromium and off by default, so shipped browsers send none of these without an opt-in flag or origin trial.

<iframe src="https://embed.example.re/"
  policy="sync-xhr=?0"></iframe>

Directives

force-load-at-top

The force-load-at-top directive instructs the browser to load the document scrolled to the top, preventing scroll position restoration or fragment navigation from placing the viewport elsewhere on initial load. Boolean.

js-profiling

The js-profiling directive enables the JavaScript Self-Profiling API for the document. When active, the Profiler constructor becomes available, allowing in-page performance sampling of JavaScript execution. Boolean, off until the header enables it, available in Chromium without any flag.

sync-xhr

The sync-xhr directive controls whether synchronous XMLHttpRequest calls are allowed. Blocking synchronous XHR prevents main-thread stalls caused by synchronous network requests. Set to ?0 to block. The directive is gated behind an experimental flag in Chromium, so a default browser ignores the value.

js-profiling-mode

The js-profiling-mode directive tunes the JavaScript Self-Profiling API, accepting eager or lazy to control when the profiler machinery initializes. Unlike js-profiling, this directive sits behind an experimental flag in Chromium.

expect-no-linked-resources

The expect-no-linked-resources directive declares the document references no subresources, letting the browser skip preload scanning work on documents where scanning has nothing to find.

include-js-call-stacks-in-crash-reports

The include-js-call-stacks-in-crash-reports directive opts the document into including JavaScript call stacks in crash reports sent to the browser's crash reporting infrastructure. Boolean.

Retired proposals

The original explainer proposed a family of performance-guardrail directives: document-write, sync-script, unsized-media, oversized-images, lossless-images-max-bpp, lossy-images-max-bpp, font-display-late-swap, and layout-animations. None shipped, and the directives exist neither in the current Chromium implementation nor in the specification draft.

Example

A document policy blocking synchronous XMLHttpRequest, with violations reported to the perf endpoint.

Document-Policy: sync-xhr=?0;report-to=perf

A site enabling the JavaScript Self-Profiling API. The js-profiling directive makes the Profiler constructor available to scripts on the page.

Document-Policy: js-profiling

A report-only deployment monitoring synchronous API usage before enforcement. Violations generate reports without blocking the behavior.

Document-Policy-Report-Only: sync-xhr=?0;report-to=perf

An iframe requiring embedded content to comply with a policy. The browser sends Sec-Required-Document-Policy on the subframe request. If the embedded server does not return a compatible policy, the browser blocks the content.

Require-Document-Policy: sync-xhr=?0

Multiple directives combined. Synchronous XHR is blocked while crash-report call stacks and top-of-page loading are enabled.

Document-Policy: sync-xhr=?0, force-load-at-top, include-js-call-stacks-in-crash-reports

See also

Last updated: September 21, 2026