# Document-Policy violation (/en/docs/web-security/reporting-api/reports/document-policy-violation)



A `document-policy-violation` report tells you the page did something a [Document-Policy](/en/docs/web-security/policies/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.

<Callout type="warn" title="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.
</Callout>

## When the browser sends it [#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 [#payload-example]

```json
{
  "type": "document-policy-violation",
  "age": 420,
  "url": "https://example.com/",
  "user_agent": "Mozilla/5.0 ...",
  "body": {
    "policyId": "document-write",
    "disposition": "enforce",
    "message": "Document policy violation: document-write is not allowed.",
    "sourceFile": "https://example.com/script.js",
    "lineNumber": 11,
    "columnNumber": 12
  }
}
```

Every `document-policy-violation` report body carries these fields inside the shared report envelope.

## Field reference [#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 [#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`](/en/docs/web-security/reporting-api/headers/reporting-endpoints). CentralCSP collects the
[document-policy stream](/en/docs/platform/monitoring/document-policy).

## What it tells you about security [#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 [#gotchas]

<Callout type="info">
  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.
</Callout>

## Browser support [#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 [#see-also]

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

## Sources [#sources]

* [WICG, Document Policy](https://wicg.github.io/document-policy/)
* [MDN, Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API)