Document-Policy violation
The document-policy-violation report fires when a page breaks a constraint set by Document-Policy.
Last update:
A document-policy-violation report tells you the page did something a Document-Policy constraint forbids, for example calling document.write or loading
an oversized image when those are restricted. It names the configuration point that
was violated and where it happened.
Experimental
Document-Policy is a WICG draft, not a W3C standard, and is Chromium-led. The set of configuration points and the report body are not stable.
When the browser sends it
When the page violates a configuration point the document policy constrains. Run
Document-Policy-Report-Only to see violations without enforcing, useful because the
set of configuration points is implementation-defined and you want to confirm what
actually fires before you block.
Payload example
{
"type": "document-policy-violation",
"age": 420,
"url": "https://api-next.centralcsp.com/",
"user_agent": "Mozilla/5.0 ...",
"body": {
"policyId": "document-write",
"disposition": "enforce",
"message": "Document policy violation: document-write is not allowed.",
"sourceFile": "https://api-next.centralcsp.com/script.js",
"lineNumber": 11,
"columnNumber": 12
}
}Every document-policy-violation report body carries these fields inside the shared report envelope.
Field reference
| Field | Meaning |
|---|---|
policyId | The configuration point that was violated, for example document-write. |
disposition | enforce, or report in Report-Only mode. |
message | A human-readable description of the violation. |
sourceFile | The file that triggered it. |
lineNumber / columnNumber | The location in that file. |
How to receive it
Add a report-to parameter to the Document-Policy header (or its Report-Only
variant) and declare that endpoint in Reporting-Endpoints. CentralCSP collects the
document-policy stream.
What it tells you about security
The constraints that matter most reduce real footguns: blocking document.write
closes a script-injection and performance hazard, for instance. A violation report
points you straight at the legacy code still relying on the behavior you want to
retire.
Gotchas
The POSTed report names the field policyId. The in-browser ReportingObserver interface exposes the same value as featureId, so parse received reports on policyId and read featureId only in browser-side code.
Browser support
Chromium-based browsers only; experimental, and there is no normative registry of configuration points, so the available constraints are implementation-defined.
See also
- Document-Policy
- Document-Policy explained (guide)
- crash report
- Document-Policy monitoring in CentralCSP
- Reporting-Endpoints header
- The report delivery format