@mozilla/nimbus-schemas 2025.1.1 → 3001.0.0

package/README.md

@@ -10,29 +10,55 @@ This directory contains a package of schemas published to various repositories f
 - node ^16
 - yarn ^1.22
 
-#### Common Operations
+### Common Operations
 From project root (i.e., parent to this directory)
 - Build: `make schemas_build`
 - Run linting and tests: `make schemas_check`
 - Code formatting: `make schemas_format`
 
-#### Building Python Schemas Package
-`make schemas_build_pypi`
 
-#### Building Typescript Schemas Package
-`make schemas_build_npm`
+### Adding New Schemas
+
+**Example**
+Creating a new sub-package `new_stuff`
+1. Add new directory `mozilla_nimbus_schemas` / `new_stuff` with schemas inside.
+1. Add `new_stuff` schemas to the `new_stuff` directory's `__init__.py` file.
+1. Add `new_stuff` to top level `__init__.py`:
+    >`from mozilla_nimbus_schemas.new_stuff import *`
+1. Generate Typescript and/or JSON Schemas for `new_stuff` by updating the `generate_json_schema.py` script like so:
+    
+    a. Import `new_stuff` alongside existing `mozilla_nimbus_schemas` imports, e.g.,
+      >`from mozilla_nimbus_schemas import experiments, jetstream, new_stuff`
+  
+    b. (optional) Add `new_stuff` to Typescript generation
+    * Update `TS_SCHEMA_PACKAGES` list, e.g.,
+      >`TS_SCHEMA_PACKAGES = [experiments, jetstream, new_stuff]`
+
+    c. (optional) Add `new_stuff` to JSON Schema generation
+    * Update `JSON_SCHEMA_PACKAGES` list, e.g.,
+      >`JSON_SCHEMA_PACKAGES = [experiments, new_stuff]`
+
+1. Build everything with `make schemas_build`
+
+1. Update the version (see [Versioning](#versioningversioning) below).
 
 ## Schemas
 ### Jetstream
 
 Contains schemas describing analysis results, metadata, and errors from [Jetstream](https://github.com/mozilla/jetstream).
 
+### Experiments
+
+Defines the schemas used for validating the Experimenter v6 API. Previously defined in the now-deprecated [`nimbus-shared`](https://github.com/mozilla/nimbus-shared).
+
 
 ## Deployment
 The build and deployment occurs automatically through CI. A deployment is triggered on merges into the `main` branch when the version number changes. Schemas are published to various repos for access in different languages.
 
-#### Versioning
-`mozilla-nimbus-schemas` uses a date-based versioning scheme (`CalVer`). The format is `yyyy.m.MINOR`, where `m` is the non-zero-padded month, and `MINOR` is an incrementing number starting from 1 for each month. Notably, this `MINOR` number does NOT correspond to the day of the month. For example, the second release in June of 2023 would have a version of `2023.6.2`.
+### Versioning
+`mozilla-nimbus-schemas` uses semantic versioning (`semver`) of `major.minor.patch`. Previously, we
+used a date-based versioning scheme (`CalVer`), which is why the version is so high (3000+). Any
+breaking changes should result in an increase in the major version.
 
 #### Version Updates
 1. To update the published package versions, update the `VERSION` file in this directory.

package/index.d.ts

@@ -7,7 +7,7 @@
  */
 
 /**
- * A unique, stable indentifier for the user used as an input to bucket hashing.
+ * A unique, stable identifier for the user used as an input to bucket hashing.
  */
 export type RandomizationUnit = "normandy_id" | "nimbus_id" | "user_id" | "group_id";
 export type DesktopApplication = "firefox-desktop" | "firefox-desktop-background-task";
@@ -100,7 +100,7 @@ export interface DesktopAllVersionsNimbusExperiment {
   /**
    * A list of featureIds the experiment contains configurations for.
    */
-  featureIds?: string[];
+  featureIds: string[];
   /**
    * A JEXL targeting expression used to filter out experiments.
    */
@@ -145,6 +145,7 @@ export interface DesktopAllVersionsNimbusExperiment {
    * If null, all locales are targeted.
    */
   locales?: string[] | null;
+  localizations?: ExperimentLocalizations | null;
   /**
    * The date that this experiment was first published to Remote Settings.
    *
@@ -187,7 +188,6 @@ export interface DesktopAllVersionsNimbusExperiment {
    * Only used by Firefox Labs Opt-Ins.
    */
   requiresRestart?: boolean;
-  localizations?: ExperimentLocalizations | null;
 }
 export interface ExperimentBucketConfig {
   randomizationUnit: RandomizationUnit;
@@ -206,7 +206,7 @@ export interface ExperimentBucketConfig {
   /**
    * The total number of buckets.
    *
-   * You can assume this will always be 10000
+   * You can assume this will always be 10000.
    */
   total: number;
 }
@@ -220,6 +220,17 @@ export interface ExperimentOutcome {
    */
   priority: string;
 }
+/**
+ * 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;
+  };
+}
 /**
  * The branch definition supported on all Firefox Desktop versions.
  *
@@ -268,118 +279,6 @@ export interface DesktopPre95FeatureConfig {
   };
   enabled: false;
 }
-/**
- * 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 feature.
- */
-export interface DesktopFeature {
-  /**
-   * The description of the feature.
-   */
-  description: string;
-  /**
-   * Whether or not this feature records exposure telemetry.
-   */
-  hasExposure: boolean;
-  /**
-   * A description of the exposure telemetry collected by this feature.
-   *
-   * Only required if hasExposure is true.
-   */
-  exposureDescription?: string;
-  /**
-   * The owner of the feature.
-   */
-  owner: string;
-  /**
-   * If true, the feature values will be cached in prefs so that they can be read before Nimbus is initialized during Firefox startup.
-   */
-  isEarlyStartup?: boolean;
-  /**
-   * The applications that can enroll in experiments for this feature.
-   *
-   * Defaults to "firefox-desktop".
-   */
-  applications?: DesktopApplication[];
-  /**
-   * The variables that this feature can set.
-   */
-  variables: {
-    [k: string]: DesktopFeatureVariable;
-  };
-  schema?: NimbusFeatureSchema;
-}
-/**
- * A feature variable.
- */
-export interface DesktopFeatureVariable {
-  /**
-   * A description of the feature.
-   */
-  description: string;
-  type: FeatureVariableType;
-  /**
-   * An optional list of possible string or integer values.
-   *
-   * Only allowed when type is string or int.
-   *
-   * The types in the enum must match the type of the field.
-   */
-  enum?: string[] | number[];
-  /**
-   * A pref that provides the default value for a feature when none is present.
-   */
-  fallbackPref?: string;
-  /**
-   * A pref that should be set to the value of this variable when enrolling in experiments.
-   *
-   * Using a string is deprecated and unsupported in Firefox 124+.
-   */
-  setPref?: string | SetPref;
-}
-export interface SetPref {
-  branch: PrefBranch;
-  /**
-   * The name of the pref to set.
-   */
-  pref: string;
-}
-/**
- * Information about a JSON schema.
- */
-export interface NimbusFeatureSchema {
-  /**
-   * The resource:// or chrome:// URI that can be loaded at runtime within Firefox.
-   *
-   * Required by Firefox so that Nimbus can import the schema for validation.
-   */
-  uri: string;
-  /**
-   * The path to the schema file in the source checkout.
-   *
-   * Required by Experimenter so that it can find schema files in source checkouts.
-   */
-  path: string;
-}
-/**
- * The Firefox Desktop-specific feature manifest.
- *
- * Firefox Desktop requires different fields for its features compared to the general
- * Nimbus feature manifest.
- */
-export interface DesktopFeatureManifest {
-  [k: string]: DesktopFeature;
-}
 /**
  * A Nimbus experiment for Firefox Desktop.
  *
@@ -447,7 +346,7 @@ export interface DesktopNimbusExperiment {
   /**
    * A list of featureIds the experiment contains configurations for.
    */
-  featureIds?: string[];
+  featureIds: string[];
   /**
    * A JEXL targeting expression used to filter out experiments.
    */
@@ -492,6 +391,7 @@ export interface DesktopNimbusExperiment {
    * If null, all locales are targeted.
    */
   locales?: string[] | null;
+  localizations?: ExperimentLocalizations | null;
   /**
    * The date that this experiment was first published to Remote Settings.
    *
@@ -534,7 +434,6 @@ export interface DesktopNimbusExperiment {
    * Only used by Firefox Labs Opt-Ins.
    */
   requiresRestart?: boolean;
-  localizations?: ExperimentLocalizations | null;
 }
 /**
  * The branch definition supported on Firefox Desktop 95+.
@@ -560,15 +459,154 @@ export interface DesktopExperimentBranch {
   firefoxLabsTitle?: string | null;
 }
 /**
- * The SDK-specific feature manifest.
+ * A Nimbus experiment for Nimbus SDK-based applications.
  */
-export interface SdkFeatureManifest {
-  [k: string]: SdkFeature;
+export interface SdkNimbusExperiment {
+  /**
+   * Version of the NimbusExperiment schema this experiment refers to
+   */
+  schemaVersion: string;
+  /**
+   * Unique identifier for the experiment
+   */
+  slug: string;
+  /**
+   * Unique identifier for the experiiment.
+   *
+   * This is a duplicate of slug, but is required field for all Remote Settings records.
+   */
+  id: string;
+  /**
+   * A slug identifying the targeted product of this experiment.
+   *
+   * It should be a lowercased_with_underscores name that is short and unambiguous and it should match the app_name found in https://probeinfo.telemetry.mozilla.org/glean/repositories. Examples are "fenix" and "firefox_desktop".
+   */
+  appName: string;
+  /**
+   * The platform identifier for the targeted app.
+   *
+   * This should match app's identifier exactly as it appears in the relevant app store listing (for relevant platforms) or the app's Glean initialization (for other platforms).
+   *
+   * Examples are "org.mozilla.firefox_beta" and "firefox-desktop".
+   */
+  appId: string;
+  /**
+   * A specific channel of an application such as "nightly", "beta", or "release".
+   */
+  channel: string;
+  /**
+   * Public name of the experiment that will be displayed on "about:studies".
+   */
+  userFacingName: string;
+  /**
+   * Short public description of the experiment that will be displayed on "about:studies".
+   */
+  userFacingDescription: string;
+  /**
+   * When this property is set to true, the SDK should not enroll new users into the experiment that have not already been enrolled.
+   */
+  isEnrollmentPaused: boolean;
+  /**
+   * 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
+   */
+  isRollout?: boolean;
+  bucketConfig: ExperimentBucketConfig;
+  /**
+   * A list of outcomes relevant to the experiment analysis.
+   */
+  outcomes?: ExperimentOutcome[];
+  /**
+   * A list of featureIds the experiment contains configurations for.
+   */
+  featureIds: string[];
+  /**
+   * A JEXL targeting expression used to filter out experiments.
+   */
+  targeting?: string | null;
+  /**
+   * Actual publish date of the experiment.
+   *
+   * Note that this value is expected to be null in Remote Settings.
+   */
+  startDate: string | null;
+  /**
+   * Actual enrollment end date of the experiment.
+   *
+   * Note that this value is expected to be null in Remote Settings.
+   */
+  enrollmentEndDate?: string | null;
+  /**
+   * Actual end date of this experiment.
+   *
+   * Note that this field is expected to be null in Remote Settings.
+   */
+  endDate: string | null;
+  /**
+   * Duration of the experiment from the start date in days.
+   *
+   * Note that this property is only used during the analysis phase (i.e., not by the SDK).
+   */
+  proposedDuration?: number;
+  /**
+   * This represents the number of days that we expect to enroll new users.
+   *
+   * Note that this property is only used during the analysis phase (i.e., not by the SDK).
+   */
+  proposedEnrollment: number;
+  /**
+   * The slug of the reference branch (i.e., the branch we consider "control").
+   */
+  referenceBranch: string | null;
+  /**
+   * The list of locale codes (e.g., "en-US" or "fr") that this experiment is targeting.
+   *
+   * If null, all locales are targeted.
+   */
+  locales?: string[] | null;
+  /**
+   * Per-locale localization substitutions.
+   */
+  localizations?: ExperimentLocalizations | null;
+  /**
+   * The date that this experiment was first published to Remote Settings.
+   *
+   * If null, it has not yet been published.
+   */
+  publishedDate?: string | null;
+  /**
+   * Branch configuration for the SDK experiment.
+   */
+  branches: SdkExperimentBranch[];
+}
+/**
+ * The branch definition for SDK-based applications.
+ *
+ * Supported on Firefox for Android 96+, Firefox for iOS 39+, and all versions of Cirrus.
+ */
+export interface SdkExperimentBranch {
+  /**
+   * 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[];
 }
 /**
  * A feature.
  */
-export interface SdkFeature {
+export interface DesktopFeature {
   /**
    * The description of the feature.
    */
@@ -583,59 +621,143 @@ export interface SdkFeature {
    * Only required if hasExposure is true.
    */
   exposureDescription?: string;
+  /**
+   * The owner of the feature.
+   */
+  owner: string;
+  /**
+   * If true, the feature values will be cached in prefs so that they can be read before Nimbus is initialized during Firefox startup.
+   */
+  isEarlyStartup?: boolean;
+  /**
+   * The applications that can enroll in experiments for this feature.
+   *
+   * Defaults to "firefox-desktop".
+   */
+  applications?: DesktopApplication[];
   /**
    * The variables that this feature can set.
    */
   variables: {
-    [k: string]: SdkFeatureVariable;
+    [k: string]: DesktopFeatureVariable;
   };
+  schema?: NimbusFeatureSchema;
+  /**
+   * If true, clients can enroll in multiple experiments and rollouts that use this feature.
+   */
+  allowCoenrollment?: boolean;
 }
 /**
  * A feature variable.
  */
-export interface SdkFeatureVariable {
+export interface DesktopFeatureVariable {
   /**
    * A description of the feature.
    */
   description: string;
   type: FeatureVariableType;
   /**
-   * An optional list of possible string values.
+   * An optional list of possible string or integer values.
    *
-   * Only allowed when type is string.
+   * Only allowed when type is string or int.
+   *
+   * The types in the enum must match the type of the field.
    */
-  enum?: string[];
+  enum?: string[] | number[];
+  /**
+   * A pref that provides the default value for a feature when none is present.
+   */
+  fallbackPref?: string;
+  /**
+   * A pref that should be set to the value of this variable when enrolling in experiments.
+   *
+   * Using a string is deprecated and unsupported in Firefox 124+.
+   */
+  setPref?: string | SetPref;
+}
+export interface SetPref {
+  branch: PrefBranch;
+  /**
+   * The name of the pref to set.
+   */
+  pref: string;
 }
 /**
- * A Nimbus experiment for Nimbus SDK-based applications.
+ * Information about a JSON schema.
  */
-export interface SdkNimbusExperiment {
+export interface NimbusFeatureSchema {
   /**
-   * Branch configuration for the experiment.
+   * The resource:// or chrome:// URI that can be loaded at runtime within Firefox.
+   *
+   * Required by Firefox so that Nimbus can import the schema for validation.
    */
-  branches: SdkExperimentBranch[];
+  uri: string;
+  /**
+   * The path to the schema file in the source checkout.
+   *
+   * Required by Experimenter so that it can find schema files in source checkouts.
+   */
+  path: string;
 }
 /**
- * The branch definition for SDK-based applications
+ * The Firefox Desktop-specific feature manifest.
  *
- * Supported on Firefox for Android 96+ and Firefox for iOS 39+ and all versions of
- * Cirrus.
+ * Firefox Desktop requires different fields for its features compared to the general
+ * Nimbus feature manifest.
  */
-export interface SdkExperimentBranch {
+export interface DesktopFeatureManifest {
+  [k: string]: DesktopFeature;
+}
+/**
+ * The SDK-specific feature manifest.
+ */
+export interface SdkFeatureManifest {
+  [k: string]: SdkFeature;
+}
+/**
+ * A feature.
+ */
+export interface SdkFeature {
   /**
-   * Identifier for the branch.
+   * The description of the feature.
    */
-  slug: string;
+  description: string;
   /**
-   * Relative ratio of population for the branch.
+   * Whether or not this feature records exposure telemetry.
+   */
+  hasExposure: boolean;
+  /**
+   * A description of the exposure telemetry collected by this feature.
    *
-   * e.g., if branch A=1 and branch B=3, then branch A would get 25% of the population.
+   * Only required if hasExposure is true.
    */
-  ratio: number;
+  exposureDescription?: string;
   /**
-   * An array of feature configurations.
+   * The variables that this feature can set.
    */
-  features: ExperimentFeatureConfig[];
+  variables: {
+    [k: string]: SdkFeatureVariable;
+  };
+  /**
+   * If true, clients can enroll in multiple experiments and rollouts that use this feature.
+   */
+  "allow-coenrollment"?: boolean;
+}
+/**
+ * A feature variable.
+ */
+export interface SdkFeatureVariable {
+  /**
+   * A description of the feature.
+   */
+  description: string;
+  type: FeatureVariableType;
+  /**
+   * An optional list of possible string values.
+   *
+   * Only allowed when type is string.
+   */
+  enum?: string[];
 }
 export interface AnalysisError {
   analysis_basis?: AnalysisBasis | null;

package/package.json

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

package/schemas/DesktopAllVersionsNimbusExperiment.schema.json

@@ -142,6 +142,16 @@
       ],
       "description": "The list of locale codes (e.g., \"en-US\" or \"fr\") that this experiment is targeting. If null, all locales are targeted."
     },
+    "localizations": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ExperimentLocalizations"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "publishedDate": {
       "anyOf": [
         {
@@ -222,16 +232,6 @@
     "requiresRestart": {
       "description": "Does the experiment require a restart to take effect? Only used by Firefox Labs Opt-Ins.",
       "type": "boolean"
-    },
-    "localizations": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/ExperimentLocalizations"
-        },
-        {
-          "type": "null"
-        }
-      ]
     }
   },
   "required": [
@@ -245,6 +245,7 @@
     "userFacingDescription",
     "isEnrollmentPaused",
     "bucketConfig",
+    "featureIds",
     "startDate",
     "endDate",
     "proposedEnrollment",
@@ -323,7 +324,7 @@
         },
         "feature": {
           "$ref": "#/$defs/DesktopPre95FeatureConfig",
-          "description": "The feature key must be provided with values to prevent crashes if the is encountered by Desktop clients earlier than version 95."
+          "description": "The feature key must be provided with values to prevent crashes if the experiment is encountered by Desktop clients earlier than version 95."
         }
       },
       "required": [
@@ -373,7 +374,7 @@
           "type": "integer"
         },
         "total": {
-          "description": "The total number of buckets. You can assume this will always be 10000",
+          "description": "The total number of buckets. You can assume this will always be 10000.",
           "type": "integer"
         }
       },
@@ -431,7 +432,7 @@
       "type": "object"
     },
     "RandomizationUnit": {
-      "description": "A unique, stable indentifier for the user used as an input to bucket hashing.",
+      "description": "A unique, stable identifier for the user used as an input to bucket hashing.",
       "enum": [
         "normandy_id",
         "nimbus_id",

package/schemas/DesktopFeature.schema.json

@@ -42,6 +42,10 @@
     "schema": {
       "$ref": "#/$defs/NimbusFeatureSchema",
       "description": "An optional JSON schema that describes the feature variables."
+    },
+    "allowCoenrollment": {
+      "description": "If true, clients can enroll in multiple experiments and rollouts that use this feature.",
+      "type": "boolean"
     }
   },
   "required": [

package/schemas/DesktopFeatureManifest.schema.json

@@ -62,6 +62,10 @@
         "schema": {
           "$ref": "#/$defs/NimbusFeatureSchema",
           "description": "An optional JSON schema that describes the feature variables."
+        },
+        "allowCoenrollment": {
+          "description": "If true, clients can enroll in multiple experiments and rollouts that use this feature.",
+          "type": "boolean"
         }
       },
       "required": [