@mozilla/nimbus-schemas 2024.11.1 → 2024.11.3

package/index.d.ts

@@ -134,12 +134,9 @@ export interface DesktopFeatureManifest {
   [k: string]: DesktopFeature;
 }
 /**
- * The experiment definition accessible to:
- *
- * 1. The Nimbus SDK via Remote Settings
- * 2. Jetstream via the Experimenter API
+ * A Nimbus experiment for Firefox Desktop.
  */
-export interface NimbusExperiment {
+export interface DesktopNimbusExperiment {
   /**
    * Version of the NimbusExperiment schema this experiment refers to
    */
@@ -192,18 +189,6 @@ export interface NimbusExperiment {
    * See-also: https://mozilla-hub.atlassian.net/browse/SDK-405
    */
   isRollout?: boolean;
-  /**
-   * When this property is set to true, treat this experiment as aFirefox Labs experiment
-   */
-  isFirefoxLabsOptIn?: boolean;
-  /**
-   * An optional string containing the Fluent ID for the title of the opt-in
-   */
-  firefoxLabsTitle?: string;
-  /**
-   * An optional string containing the Fluent ID for the description of the opt-in
-   */
-  firefoxLabsDescription?: string;
   bucketConfig: ExperimentBucketConfig;
   /**
    * A list of outcomes relevant to the experiment analysis.
@@ -213,13 +198,6 @@ export interface NimbusExperiment {
    * A list of featureIds the experiment contains configurations for.
    */
   featureIds?: string[];
-  /**
-   * Branch configuration for the experiment.
-   */
-  branches:
-    | ExperimentSingleFeatureBranch[]
-    | ExperimentMultiFeatureDesktopBranch[]
-    | ExperimentMultiFeatureMobileBranch[];
   /**
    * A JEXL targeting expression used to filter out experiments.
    */
@@ -258,11 +236,6 @@ export interface NimbusExperiment {
    * The slug of the reference branch (i.e., the branch we consider "control").
    */
   referenceBranch: string | null;
-  /**
-   * Opt out of feature schema validation. Only supported on desktop.
-   */
-  featureValidationOptOut?: boolean;
-  localizations?: ExperimentLocalizations | null;
   /**
    * The list of locale codes (e.g., "en-US" or "fr") that this experiment is targeting.
    *
@@ -275,6 +248,27 @@ export interface NimbusExperiment {
    * If null, it has not yet been published.
    */
   publishedDate?: string | null;
+  /**
+   * Branch configuration for the experiment.
+   */
+  branches: DesktopExperimentBranch[];
+  /**
+   * When this property is set to true, treat this experiment as aFirefox Labs experiment
+   */
+  isFirefoxLabsOptIn?: boolean;
+  /**
+   * An optional string containing the Fluent ID for the title of the opt-in
+   */
+  firefoxLabsTitle?: string;
+  /**
+   * An optional string containing the Fluent ID for the description of the opt-in
+   */
+  firefoxLabsDescription?: string;
+  /**
+   * Opt out of feature schema validation.
+   */
+  featureValidationOptOut?: boolean;
+  localizations?: ExperimentLocalizations | null;
 }
 export interface ExperimentBucketConfig {
   randomizationUnit: RandomizationUnit;
@@ -308,12 +302,9 @@ export interface ExperimentOutcome {
   priority: string;
 }
 /**
- * A single-feature branch definition.
- *
- * Supported by Firefox Desktop for versions before 95, Firefox for Android for versions
- * before 96, and Firefox for iOS for versions before 39.
+ * The branch definition supported on Firefox Desktop 95+.
  */
-export interface ExperimentSingleFeatureBranch {
+export interface DesktopExperimentBranch {
   /**
    * Identifier for the branch.
    */
@@ -324,7 +315,15 @@ export interface ExperimentSingleFeatureBranch {
    * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
    */
   ratio: number;
-  feature: ExperimentFeatureConfig;
+  /**
+   * An array of feature configurations.
+   */
+  features: ExperimentFeatureConfig[];
+  feature: DesktopTombstoneFeatureConfig;
+  /**
+   * An optional string containing the title of the branch
+   */
+  firefoxLabsTitle?: string;
 }
 export interface ExperimentFeatureConfig {
   /**
@@ -340,30 +339,6 @@ export interface ExperimentFeatureConfig {
     [k: string]: unknown;
   };
 }
-/**
- * The branch definition supported on Firefox Desktop 95+.
- */
-export interface ExperimentMultiFeatureDesktopBranch {
-  /**
-   * Identifier for the branch.
-   */
-  slug: string;
-  /**
-   * Relative ratio of population for the branch.
-   *
-   * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
-   */
-  ratio: number;
-  /**
-   * An array of feature configurations.
-   */
-  features: ExperimentFeatureConfig[];
-  feature: DesktopTombstoneFeatureConfig;
-  /**
-   * An optional string containing the title of the branch
-   */
-  firefoxLabsTitle: string;
-}
 export interface DesktopTombstoneFeatureConfig {
   featureId: "unused-feature-id-for-legacy-support";
   value: {
@@ -372,11 +347,32 @@ export interface DesktopTombstoneFeatureConfig {
   enabled: false;
 }
 /**
- * The branch definition for mobile browsers.
+ * Per-locale localization substitutions.
+ *
+ * The top level key is the locale (e.g., "en-US" or "fr"). Each entry is a mapping of
+ * string IDs to their localized equivalents.
+ */
+export interface ExperimentLocalizations {
+  [k: string]: {
+    [k: string]: string;
+  };
+}
+/**
+ * A Nimbus experiment for Nimbus SDK-based applications.
+ */
+export interface SdkNimbusExperiment {
+  /**
+   * Branch configuration for the experiment.
+   */
+  branches: SdkExperimentBranch[];
+}
+/**
+ * The branch definition for SDK-based applications
  *
- * Supported on Firefox for Android 96+ and Firefox for iOS 39+.
+ * Supported on Firefox for Android 96+ and Firefox for iOS 39+ and all versions of
+ * Cirrus.
  */
-export interface ExperimentMultiFeatureMobileBranch {
+export interface SdkExperimentBranch {
   /**
    * Identifier for the branch.
    */
@@ -392,19 +388,6 @@ export interface ExperimentMultiFeatureMobileBranch {
    */
   features: ExperimentFeatureConfig[];
 }
-/**
- * Per-locale localization substitutions.
- *
- * The top level key is the locale (e.g., "en-US" or "fr"). Each entry is a mapping of
- * string IDs to their localized equivalents.
- *
- * Only supported on desktop.
- */
-export interface ExperimentLocalizations {
-  [k: string]: {
-    [k: string]: string;
-  };
-}
 /**
  * The SDK-specific feature manifest.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/nimbus-schemas",
-  "version": "2024.11.1",
+  "version": "2024.11.3",
   "description": "Schemas used by Mozilla Nimbus and related projects.",
   "main": "index.d.ts",
   "repository": {

package/schemas/{NimbusExperiment.schema.json → DesktopNimbusExperiment.schema.json}

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2019-09/schema",
-  "title": "NimbusExperiment",
-  "description": "The experiment definition accessible to: 1. The Nimbus SDK via Remote Settings 2. Jetstream via the Experimenter API",
+  "title": "DesktopNimbusExperiment",
+  "description": "A Nimbus experiment for Firefox Desktop.",
   "type": "object",
   "properties": {
     "schemaVersion": {
@@ -44,18 +44,6 @@
       "description": "When this property is set to true, treat this experiment as a rollout. Rollouts are currently handled as single-branch experiments separated from the bucketing namespace for normal experiments. See-also: https://mozilla-hub.atlassian.net/browse/SDK-405",
       "type": "boolean"
     },
-    "isFirefoxLabsOptIn": {
-      "description": "When this property is set to true, treat this experiment as aFirefox Labs experiment",
-      "type": "boolean"
-    },
-    "firefoxLabsTitle": {
-      "description": "An optional string containing the Fluent ID for the title of the opt-in",
-      "type": "string"
-    },
-    "firefoxLabsDescription": {
-      "description": "An optional string containing the Fluent ID for the description of the opt-in",
-      "type": "string"
-    },
     "bucketConfig": {
       "$ref": "#/$defs/ExperimentBucketConfig",
       "description": "Bucketing configuration."
@@ -74,29 +62,6 @@
       },
       "type": "array"
     },
-    "branches": {
-      "anyOf": [
-        {
-          "items": {
-            "$ref": "#/$defs/ExperimentSingleFeatureBranch"
-          },
-          "type": "array"
-        },
-        {
-          "items": {
-            "$ref": "#/$defs/ExperimentMultiFeatureDesktopBranch"
-          },
-          "type": "array"
-        },
-        {
-          "items": {
-            "$ref": "#/$defs/ExperimentMultiFeatureMobileBranch"
-          },
-          "type": "array"
-        }
-      ],
-      "description": "Branch configuration for the experiment."
-    },
     "targeting": {
       "anyOf": [
         {
@@ -163,20 +128,6 @@
       ],
       "description": "The slug of the reference branch (i.e., the branch we consider \"control\")."
     },
-    "featureValidationOptOut": {
-      "description": "Opt out of feature schema validation. Only supported on desktop.",
-      "type": "boolean"
-    },
-    "localizations": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/ExperimentLocalizations"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
     "locales": {
       "anyOf": [
         {
@@ -202,6 +153,39 @@
         }
       ],
       "description": "The date that this experiment was first published to Remote Settings. If null, it has not yet been published."
+    },
+    "branches": {
+      "description": "Branch configuration for the experiment.",
+      "items": {
+        "$ref": "#/$defs/DesktopExperimentBranch"
+      },
+      "type": "array"
+    },
+    "isFirefoxLabsOptIn": {
+      "description": "When this property is set to true, treat this experiment as aFirefox Labs experiment",
+      "type": "boolean"
+    },
+    "firefoxLabsTitle": {
+      "description": "An optional string containing the Fluent ID for the title of the opt-in",
+      "type": "string"
+    },
+    "firefoxLabsDescription": {
+      "description": "An optional string containing the Fluent ID for the description of the opt-in",
+      "type": "string"
+    },
+    "featureValidationOptOut": {
+      "description": "Opt out of feature schema validation.",
+      "type": "boolean"
+    },
+    "localizations": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ExperimentLocalizations"
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "required": [
@@ -215,11 +199,11 @@
     "userFacingDescription",
     "isEnrollmentPaused",
     "bucketConfig",
-    "branches",
     "startDate",
     "endDate",
     "proposedEnrollment",
-    "referenceBranch"
+    "referenceBranch",
+    "branches"
   ],
   "dependentSchemas": {
     "isFirefoxLabsOptIn": {
@@ -268,6 +252,41 @@
     }
   },
   "$defs": {
+    "DesktopExperimentBranch": {
+      "description": "The branch definition supported on Firefox Desktop 95+.",
+      "properties": {
+        "slug": {
+          "description": "Identifier for the branch.",
+          "type": "string"
+        },
+        "ratio": {
+          "description": "Relative ratio of population for the branch. e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.",
+          "type": "integer"
+        },
+        "features": {
+          "description": "An array of feature configurations.",
+          "items": {
+            "$ref": "#/$defs/ExperimentFeatureConfig"
+          },
+          "type": "array"
+        },
+        "feature": {
+          "$ref": "#/$defs/DesktopTombstoneFeatureConfig",
+          "description": "The feature key must be provided with values to prevent crashes if the is encountered by Desktop clients earlier than version 95."
+        },
+        "firefoxLabsTitle": {
+          "description": "An optional string containing the title of the branch",
+          "type": "string"
+        }
+      },
+      "required": [
+        "slug",
+        "ratio",
+        "features",
+        "feature"
+      ],
+      "type": "object"
+    },
     "DesktopTombstoneFeatureConfig": {
       "properties": {
         "featureId": {
@@ -344,69 +363,7 @@
         },
         "type": "object"
       },
-      "description": "Per-locale localization substitutions. The top level key is the locale (e.g., \"en-US\" or \"fr\"). Each entry is a mapping of string IDs to their localized equivalents. Only supported on desktop.",
-      "type": "object"
-    },
-    "ExperimentMultiFeatureDesktopBranch": {
-      "description": "The branch definition supported on Firefox Desktop 95+.",
-      "properties": {
-        "slug": {
-          "description": "Identifier for the branch.",
-          "type": "string"
-        },
-        "ratio": {
-          "description": "Relative ratio of population for the branch. e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.",
-          "type": "integer"
-        },
-        "features": {
-          "description": "An array of feature configurations.",
-          "items": {
-            "$ref": "#/$defs/ExperimentFeatureConfig"
-          },
-          "type": "array"
-        },
-        "feature": {
-          "$ref": "#/$defs/DesktopTombstoneFeatureConfig",
-          "description": "The feature key must be provided with values to prevent crashes if the is encountered by Desktop clients earlier than version 95."
-        },
-        "firefoxLabsTitle": {
-          "description": "An optional string containing the title of the branch",
-          "type": "string"
-        }
-      },
-      "required": [
-        "slug",
-        "ratio",
-        "features",
-        "feature",
-        "firefoxLabsTitle"
-      ],
-      "type": "object"
-    },
-    "ExperimentMultiFeatureMobileBranch": {
-      "description": "The branch definition for mobile browsers. Supported on Firefox for Android 96+ and Firefox for iOS 39+.",
-      "properties": {
-        "slug": {
-          "description": "Identifier for the branch.",
-          "type": "string"
-        },
-        "ratio": {
-          "description": "Relative ratio of population for the branch. e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.",
-          "type": "integer"
-        },
-        "features": {
-          "description": "An array of feature configurations.",
-          "items": {
-            "$ref": "#/$defs/ExperimentFeatureConfig"
-          },
-          "type": "array"
-        }
-      },
-      "required": [
-        "slug",
-        "ratio",
-        "features"
-      ],
+      "description": "Per-locale localization substitutions. The top level key is the locale (e.g., \"en-US\" or \"fr\"). Each entry is a mapping of string IDs to their localized equivalents.",
       "type": "object"
     },
     "ExperimentOutcome": {
@@ -426,29 +383,6 @@
       ],
       "type": "object"
     },
-    "ExperimentSingleFeatureBranch": {
-      "description": "A single-feature branch definition. Supported by Firefox Desktop for versions before 95, Firefox for Android for versions before 96, and Firefox for iOS for versions before 39.",
-      "properties": {
-        "slug": {
-          "description": "Identifier for the branch.",
-          "type": "string"
-        },
-        "ratio": {
-          "description": "Relative ratio of population for the branch. e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.",
-          "type": "integer"
-        },
-        "feature": {
-          "$ref": "#/$defs/ExperimentFeatureConfig",
-          "description": "A single feature configuration."
-        }
-      },
-      "required": [
-        "slug",
-        "ratio",
-        "feature"
-      ],
-      "type": "object"
-    },
     "RandomizationUnit": {
       "description": "A unique, stable indentifier for the user used as an input to bucket hashing.",
       "enum": [

package/schemas/SdkNimbusExperiment.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "title": "SdkNimbusExperiment",
+  "description": "A Nimbus experiment for Nimbus SDK-based applications.",
+  "type": "object",
+  "properties": {
+    "branches": {
+      "description": "Branch configuration for the experiment.",
+      "items": {
+        "$ref": "#/$defs/SdkExperimentBranch"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "branches"
+  ],
+  "$defs": {
+    "ExperimentFeatureConfig": {
+      "properties": {
+        "featureId": {
+          "description": "The identifier for the feature flag.",
+          "type": "string"
+        },
+        "value": {
+          "description": "The values that define the feature configuration. This should be validated against a schema.",
+          "type": "object"
+        }
+      },
+      "required": [
+        "featureId",
+        "value"
+      ],
+      "type": "object"
+    },
+    "SdkExperimentBranch": {
+      "description": "The branch definition for SDK-based applications Supported on Firefox for Android 96+ and Firefox for iOS 39+ and all versions of Cirrus.",
+      "properties": {
+        "slug": {
+          "description": "Identifier for the branch.",
+          "type": "string"
+        },
+        "ratio": {
+          "description": "Relative ratio of population for the branch. e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.",
+          "type": "integer"
+        },
+        "features": {
+          "description": "An array of feature configurations.",
+          "items": {
+            "$ref": "#/$defs/ExperimentFeatureConfig"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "slug",
+        "ratio",
+        "features"
+      ],
+      "type": "object"
+    }
+  }
+}