A .well-known file for website privacy declarations

How websites can declare their data practices in a machine-readable format

The idea

Most websites have a privacy policy. Most people don't read them. What if a website could declare its data practices in a machine-readable format that a browser extension could read, display, and compare against the user's preferences?

That's what .well-known/protoconsent.json does. It follows the same pattern as security.txt (RFC 9116) and .well-known/change-password: a static file at a standard path that tools can discover and consume automatically.

What it looks like

A minimal declaration for a blog that uses privacy-friendly analytics:

{
  "protoconsent": "0.2",
  "purposes": {
    "functional": {
      "used": true,
      "legal_basis": "legitimate_interest"
    },
    "analytics": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Privacy-friendly Analytics"],
      "retention": { "type": "fixed", "value": 30, "unit": "days" }
    }
  }
}

The file declares which of ProtoConsent's six purposes the site uses, under what legal basis, with which providers, and for how long data is retained. Purposes not included are treated as "not declared" (the site makes no claim). Setting "used": false explicitly states a purpose is not active.

The six purposes

The declaration uses the same purpose taxonomy as the ProtoConsent extension:

• functional - core site functionality (login, cart, preferences)
• analytics - usage measurement and reporting
• ads - advertising and ad targeting
• personalization - content personalization based on user behavior
• third_parties - embedded third-party services (maps, videos, social widgets)
• advanced_tracking - cross-site tracking, fingerprinting, user profiling

For each purpose, the site can declare: whether it's used, the legal basis (aligned with GDPR Article 6), providers involved, data sharing scope, and retention period.

A fuller example

An e-commerce site with ads, analytics, and third-party sharing:

{
  "protoconsent": "0.2",
  "last_updated": "2026-04-13",
  "purposes": {
    "functional": {
      "used": true,
      "legal_basis": "contractual",
      "retention": { "type": "session" }
    },
    "analytics": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Analytics provider"],
      "retention": { "type": "fixed", "value": 2, "unit": "years" }
    },
    "ads": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Ad network", "Retargeting pixel"],
      "sharing": "third_parties",
      "retention": { "type": "fixed", "value": 6, "unit": "months" }
    },
    "personalization": {
      "used": true,
      "legal_basis": "consent",
      "retention": { "type": "until_withdrawal" }
    },
    "third_parties": {
      "used": true,
      "legal_basis": "consent",
      "sharing": "third_parties",
      "retention": { "type": "fixed", "value": 2, "unit": "years" }
    },
    "advanced_tracking": { "used": false }
  },
  "data_handling": {
    "storage_region": "eu",
    "international_transfers": true
  },
  "links": {
    "policy": "https://shop.example.com/privacy",
    "rights": "https://shop.example.com/privacy#your-rights"
  }
}

How the extension uses it

When you visit a site that serves a .well-known/protoconsent.json, the ProtoConsent extension fetches and validates it. The declared practices are displayed in a side panel alongside the user's own preferences, using Consent Commons icons for each purpose.

This creates a two-column view: what the site says it does (declaration) and what the user wants (preferences). Users can see at a glance whether a site's stated practices align with their choices.

Self-assertion, not certification

The declaration is a voluntary, self-asserted transparency signal. It does not change how the extension enforces user preferences. Publishing a protoconsent.json file does not prove actual technical behavior: a site could declare "ads": { "used": false } while still loading ad trackers. The extension always enforces the user's own profile.

Think of it like security.txt: it's a machine-readable way for sites to say "here's what we do" that tools can consume. Trust comes from the declaration being public, inspectable, and comparable against observed behavior.

Complementary to existing standards

• GPC (Sec-GPC): signals user preference (browser to site). The declaration signals site practices (site to browser). They are complementary directions.
• ProtoConsent SDK: enables dynamic interaction (page queries extension). The declaration enables static discovery (extension reads site). A site can use one, both, or neither.
• Consent Commons: the purpose categories and legal basis values align with the Consent Commons taxonomy.

Get started

Publishing a declaration takes a few minutes:

• Generate: use the online generator to create your file interactively.
• Validate: check your file with the online validator or the GitHub Action for CI/CD.
• Publish: place the file at /.well-known/protoconsent.json on your domain. For GitHub Pages, add a .nojekyll file so the .well-known directory is served.
• List your site: add it to the public directory of sites with declarations.

For the full specification, see protoconsent-well-known.md on GitHub. The JSON Schema (v0.2) is also available for programmatic validation.