ref(core): Rename dataCollection.defaults to unlisted

`defaults` reads like "the default values". `unlisted: 'default' | 'off'`
names what the option controls: fields not listed in `dataCollection`.

Author: sentry-junior[bot]

MIGRATION.md

@@ -209,13 +209,13 @@ Sentry.init({});
 
 #### If you want to keep the v10 default behavior
 
-Set `defaults: 'off'` and turn on only what v10 collected. **Don't leave `dataCollection` unset** — that now enables broader collection.
+Set `unlisted: 'off'` and list only what v10 collected. **Don't leave `dataCollection` unset** — that now enables broader collection.
 
 ```js
 // v11 — preserves the v10 default
 Sentry.init({
   dataCollection: {
-    defaults: 'off',
+    unlisted: 'off',
     httpHeaders: { deny: ['forwarded', '-ip', 'remote-', 'via', '-user'] },
     urlQueryParams: { deny: ['forwarded', '-ip', 'remote-', 'via', '-user'] },
     stackFrameVariables: true,
@@ -224,7 +224,7 @@ Sentry.init({
 });
 ```
 
-With `defaults: 'off'`, every field you don't set collects nothing. This includes fields added in later minor releases, so upgrading never starts collecting new data on its own.
+With `unlisted: 'off'`, every field you don't list collects nothing. This includes fields added in later minor releases, so upgrading never starts collecting new data on its own. A field you do list is collected as configured: here, `httpHeaders` and `urlQueryParams` are collected except for the keys in their `deny` lists.
 
 Each key-value field (`cookies`, `urlQueryParams`, `httpHeaders.request`, `httpHeaders.response`) accepts
 `true`, `false`, `{ allow: string[] }`, or `{ deny: string[] }` for fine-grained control.

packages/core/src/types/datacollection.ts

@@ -21,18 +21,18 @@ export interface HttpHeadersCollection {
 /**
  * Controls what data the SDK collects and sends to Sentry.
  *
- * All fields are optional. Omitted fields use the documented defaults, or collect nothing when `defaults` is `'off'`.
+ * All fields are optional. Omitted fields use the documented defaults, or collect nothing when `unlisted` is `'off'`.
  */
 export interface DataCollection {
   /**
-   * The value used for every field that is not set.
+   * What the SDK collects for every field you don't list in `dataCollection`.
    *
-   * - `'on'`: Unset fields use their documented defaults.
-   * - `'off'`: Unset fields collect nothing. This also applies to fields added in future releases, so
+   * - `'default'`: Unlisted fields use their documented defaults.
+   * - `'off'`: Unlisted fields collect nothing. This also applies to fields added in future releases, so
    *   only the data you turn on explicitly is collected.
-   * @default 'on'
+   * @default 'default'
    */
-  defaults?: 'on' | 'off';
+  unlisted?: 'default' | 'off';
 
   /**
    * Automatically populate `user.*` fields from instrumentation sources.
@@ -153,7 +153,7 @@ export interface DataCollection {
 /**
  * Fully resolved `DataCollection` with all defaults applied.
  */
-export type ResolvedDataCollection = Required<Omit<DataCollection, 'httpHeaders' | 'defaults'>> & {
+export type ResolvedDataCollection = Required<Omit<DataCollection, 'httpHeaders' | 'unlisted'>> & {
   httpHeaders: Required<HttpHeadersCollection>;
   graphQL: Required<NonNullable<DataCollection['graphQL']>>;
   genAI: Required<NonNullable<DataCollection['genAI']>>;

packages/core/src/utils/data-collection/resolveDataCollectionOptions.ts

@@ -61,12 +61,12 @@ function resolveHttpHeaders(
  * Resolves the effective `DataCollection` configuration from client options.
  *
  * Precedence:
- * 1. Spec defaults, or all collection turned off when `dataCollection.defaults` is `'off'`
+ * 1. Spec defaults, or all collection turned off when `dataCollection.unlisted` is `'off'`
  * 2. Fields explicitly set in `dataCollection`
  */
 export function resolveDataCollectionOptions(options: { dataCollection?: DataCollection }): ResolvedDataCollection {
   const dc = options.dataCollection ?? {};
-  const base = dc.defaults === 'off' ? OFF : DEFAULTS;
+  const base = dc.unlisted === 'off' ? OFF : DEFAULTS;
 
   return {
     userInfo: dc.userInfo ?? base.userInfo,

packages/core/test/lib/integrations/mcp-server/capturePolicy.test.ts

@@ -448,10 +448,10 @@ describe('MCP Server Capture Policy', () => {
         { mcp: { inputs: true }, genAI: { inputs: false, outputs: false } },
         { inputs: true, outputs: false },
       ],
-      ["records nothing with defaults: 'off'", { defaults: 'off' }, { inputs: false, outputs: false }],
+      ["records nothing with unlisted: 'off'", { unlisted: 'off' }, { inputs: false, outputs: false }],
       [
-        "falls back to genAI with defaults: 'off'",
-        { defaults: 'off', genAI: { inputs: true } },
+        "falls back to genAI with unlisted: 'off'",
+        { unlisted: 'off', genAI: { inputs: true } },
         { inputs: true, outputs: false },
       ],
     ])('%s', async (_, dataCollection, expected) => {

packages/core/test/lib/utils/data-collection/resolveDataCollectionOptions.test.ts

@@ -224,7 +224,7 @@ describe('resolveDataCollectionOptions', () => {
     });
   });
 
-  describe('defaults', () => {
+  describe('unlisted', () => {
     const ALL_OFF = {
       userInfo: false,
       cookies: false,
@@ -241,13 +241,13 @@ describe('resolveDataCollectionOptions', () => {
     };
 
     it('turns off every field that is not set', () => {
-      expect(resolveDataCollectionOptions({ dataCollection: { defaults: 'off' } })).toEqual(ALL_OFF);
+      expect(resolveDataCollectionOptions({ dataCollection: { unlisted: 'off' } })).toEqual(ALL_OFF);
     });
 
     it('keeps fields that are set explicitly', () => {
       const result = resolveDataCollectionOptions({
         dataCollection: {
-          defaults: 'off',
+          unlisted: 'off',
           genAI: { inputs: true },
           urlQueryParams: { deny: ['token'] },
           frameContextLines: 7,
@@ -264,13 +264,13 @@ describe('resolveDataCollectionOptions', () => {
 
     it('turns off the unset httpHeaders direction', () => {
       expect(
-        resolveDataCollectionOptions({ dataCollection: { defaults: 'off', httpHeaders: { request: true } } })
+        resolveDataCollectionOptions({ dataCollection: { unlisted: 'off', httpHeaders: { request: true } } })
           .httpHeaders,
       ).toEqual({ request: true, response: false });
     });
 
-    it("uses spec defaults with defaults: 'on'", () => {
-      expect(resolveDataCollectionOptions({ dataCollection: { defaults: 'on' } })).toEqual(SPEC_DEFAULTS);
+    it("uses spec defaults with unlisted: 'default'", () => {
+      expect(resolveDataCollectionOptions({ dataCollection: { unlisted: 'default' } })).toEqual(SPEC_DEFAULTS);
     });
   });