@openpolicy/sdk/skills/define-config/SKILL.md

Public API for defining privacy policies with OpenPolicy

---
name: define-config
description: >
  Writing the defineConfig() object for OpenPolicyConfig — privacy and cookie — including all field types, jurisdiction requirements, and preset constants from @openpolicy/sdk.
type: core
library: openpolicy
library_version: "0.0.19"
sources:
  - jamiedavenport/openpolicy:packages/core/src/types.ts
  - jamiedavenport/openpolicy:packages/sdk/src/constants.ts
---

# openpolicy/define-config

Write and maintain the `defineConfig()` call in `openpolicy.ts`. The function is an identity function used as a type marker — it accepts `OpenPolicyConfig` and returns it unchanged.

## Setup

Minimal config with privacy policy:

```ts
// openpolicy.ts
import {
	ContractPrerequisite,
	cookies,
	dataCollected,
	defineConfig,
	LegalBases,
	thirdParties,
} from "@openpolicy/sdk";

export default defineConfig({
	company: {
		name: "Acme",
		legalName: "Acme, Inc.",
		address: "123 Main St, San Francisco, CA 94105",
		contact: { email: "privacy@acme.com" },
	},
	effectiveDate: "2026-01-01",
	jurisdictions: ["us-ca"],
	data: {
		collected: { ...dataCollected },
		context: {
			"Account Information": {
				purpose: "To create and manage user accounts",
				lawfulBasis: LegalBases.Contract,
				retention: "Until account deletion",
				provision: ContractPrerequisite("We cannot create or operate your account."),
			},
		},
	},
	thirdParties: [...thirdParties],
	cookies: {
		used: cookies,
		context: { essential: { lawfulBasis: LegalBases.LegalObligation } },
	},
	automatedDecisionMaking: [],
});
```

The `data` block keeps privacy fields together: `collected` lists field labels per category, and `context` carries the per-category metadata (`purpose`, `lawfulBasis`, `retention`, `provision`). Every key in `collected` must have a matching `context` entry — TS-enforced via `defineConfig`. The `cookies` block mirrors that pattern with `used` (categories) and `context` (Article 6 basis per category). OpenPolicy auto-detects which policies to generate from the fields you provide: a `data` block produces a privacy policy; a `cookies` block produces a cookie policy. `effectiveDate` and `jurisdictions` are shared across both.

User rights (access, erasure, portability, etc.) are **derived automatically** from `jurisdictions` — declare `eu` (GDPR) or `uk` (UK-GDPR) for the six GDPR-style rights, `us-ca` for the four CCPA rights, or any combination for the union. There is no `userRights` field on the public config. See [Supported jurisdictions](https://docs.openpolicy.sh/references/jurisdictions) for the full list of codes.

## Core Patterns

### 1. Privacy config with GDPR

Use `Compliance.GDPR` to spread the required `jurisdictions` (rights are derived automatically). Pair each collected category with a single context object holding its purpose, lawful basis, retention, and provision requirement:

```ts
import {
	ContractPrerequisite,
	cookies,
	Compliance,
	DataCategories,
	dataCollected,
	defineConfig,
	LegalBases,
	Providers,
	Retention,
	thirdParties,
	Voluntary,
} from "@openpolicy/sdk";

export default defineConfig({
	company: {
		name: "Acme",
		legalName: "Acme, Inc.",
		address: "123 Main St, San Francisco, CA 94105",
		contact: { email: "privacy@acme.com" },
	},
	effectiveDate: "2026-01-01",
	...Compliance.GDPR,
	data: {
		collected: {
			...dataCollected,
			...DataCategories.AccountInfo,
			...DataCategories.UsageData,
		},
		context: {
			"Account Information": {
				purpose: "To authenticate users and send service notifications",
				lawfulBasis: LegalBases.Contract,
				retention: Retention.UntilAccountDeletion,
				provision: ContractPrerequisite("We cannot create or operate your account."),
			},
			"Usage Data": {
				purpose: "To understand product usage and improve the service",
				lawfulBasis: LegalBases.LegitimateInterests,
				retention: Retention.NinetyDays,
				provision: Voluntary("None — your service is unaffected."),
			},
		},
	},
	thirdParties: [...thirdParties, Providers.Stripe, Providers.PostHog],
	children: { underAge: 13 },
	cookies: {
		used: cookies,
		context: {
			essential: { lawfulBasis: LegalBases.LegalObligation },
			analytics: { lawfulBasis: LegalBases.Consent },
			marketing: { lawfulBasis: LegalBases.Consent },
		},
	},
	automatedDecisionMaking: [],
});
```

`Compliance.GDPR` expands to `{ jurisdictions: ["eu"] }`. The six GDPR user rights are derived automatically from `jurisdictions: ["eu"]`. `defineConfig` infers the category set from `data.collected` and requires every category to appear in `context` — omitting any is a TS error.

### 2. Using Compliance presets

`Compliance.GDPR`, `Compliance.UK_GDPR`, and `Compliance.CCPA` are objects safe to spread directly into `defineConfig()`:

```ts
import { Compliance, defineConfig } from "@openpolicy/sdk";

// GDPR only
defineConfig({ ...Compliance.GDPR /* ... */ });

// Multi-region — union the jurisdictions; user rights are derived automatically
defineConfig({
	jurisdictions: [
		...Compliance.GDPR.jurisdictions,
		...Compliance.UK_GDPR.jurisdictions,
		...Compliance.CCPA.jurisdictions,
	],
	// ...
});
```

Each preset provides only `jurisdictions`. The Article 6 basis per data category lives in `data.context[category].lawfulBasis` (you choose), not the preset.

Available preset groups from `@openpolicy/sdk`:

| Export           | Content                                                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `DataCategories` | Named `dataCollected` entries (AccountInfo, SessionData, PaymentInfo, UsageData, DeviceInfo, LocationData, Communications) |
| `Retention`      | Retention period strings (UntilAccountDeletion, ThirtyDays, NinetyDays, OneYear, ThreeYears, AsRequiredByLaw, …)           |
| `LegalBases`     | `LegalBasis` string constants (Consent, Contract, LegitimateInterests, …)                                                  |
| `Compliance`     | Preset bundles: `GDPR`, `UK_GDPR`, `CCPA`                                                                                  |
| `Providers`      | Named third-party descriptors: Stripe, PostHog, Vercel, Sentry, Clerk, Resend, …                                           |

### 3. Cookie config

```ts
export default defineConfig({
  company: { ... },
  effectiveDate: "2026-01-01",
  jurisdictions: ["eu", "us-ca"],
  cookies: {
    used: { essential: true, analytics: true, marketing: false },
    context: {
      essential: { lawfulBasis: LegalBases.LegalObligation },
      analytics: { lawfulBasis: LegalBases.Consent },
      marketing: { lawfulBasis: LegalBases.Consent },
    },
  },
  consentMechanism: {
    hasBanner: true,
    hasPreferencePanel: true,
    canWithdraw: true,
  },
  trackingTechnologies: ["localStorage", "sessionStorage", "cookies"],
  thirdParties: [Providers.GoogleAnalytics, Providers.Cloudflare],
});
```

`cookies.used` requires `essential: true` — all other keys are `boolean` and are treated as additional cookie categories. Every enabled category in `cookies.used` must have a matching entry in `cookies.context` (TS-enforced via the `ScannedCookieKeys` interface). Presence of `cookies`, `consentMechanism`, or `trackingTechnologies` auto-detects a cookie policy.

## Common Mistakes

### HIGH — Using free-form keys in `data.context`

Wrong:

```ts
// WRONG: data.context keys must match data.collected keys (TS will reject this)
defineConfig({
	data: {
		collected: { "Account Information": ["Name", "Email"] },
		context: {
			"Providing the service": {
				// ← unrelated string
				purpose: "Account creation",
				lawfulBasis: LegalBases.Contract,
				retention: "Until account deletion",
				provision: ContractPrerequisite("We cannot create your account."),
			},
		},
	},
});
```

Correct:

```ts
defineConfig({
	data: {
		collected: { "Account Information": ["Name", "Email"] },
		context: {
			"Account Information": {
				purpose: "Account creation",
				lawfulBasis: LegalBases.Contract,
				retention: "Until account deletion",
				provision: ContractPrerequisite("We cannot create your account."),
			},
		},
	},
});
```

`data.context` is keyed by the same set of strings as `data.collected`. The renderer joins each context entry into the GDPR Art. 13(1)(c) chain: `**Account Information** — used for Account creation — Performance of a contract (Article 6(1)(b))`.

Source: `packages/core/src/types.ts`, `packages/core/src/documents/privacy.ts`

---

### MEDIUM — Not specifying jurisdictions — GDPR/CCPA sections silently absent

Wrong:

```ts
// WRONG: jurisdictions missing — Legal Basis section and GDPR/CCPA content will not appear,
// and no user rights will be derived
defineConfig({
	company: {
		/* ... */
	},
	data: { collected: {}, context: {} },
	// jurisdictions omitted
});
```

Correct:

```ts
defineConfig({
	company: {
		/* ... */
	},
	data: {
		collected: { "Account Information": ["Name"] },
		context: {
			"Account Information": {
				purpose: "Account creation",
				lawfulBasis: LegalBases.Contract,
				retention: "Until account deletion",
				provision: ContractPrerequisite("We cannot create your account."),
			},
		},
	},
	jurisdictions: ["eu", "us-ca"],
});
```

Section builders for GDPR (`eu`), UK-GDPR (`uk`), and CCPA (`us-ca`) content check the top-level `jurisdictions` field before generating output, and the user rights list is derived from the same field. Omitting `jurisdictions` (or passing an empty array) causes those sections to be silently skipped and no rights to be listed.

Source: `packages/core/src/templates/privacy/`

## Reference

- [PrivacyPolicyConfig and CookiePolicyConfig field table](./references/privacy-config.md)