feat(schemas): Add Firefox Labs fields to SDK experiment schemas (#15883)

This commit is a breaking change.

Because:

- we are bringing Firefox Labs to the SDK; and
- our Pydantic models cannot distinguish between the
  firefoxLabsDescriptionLinks field being absent or null

This commit:

- adds most Firefox Labs fields (no firefoxLabsGroup) to the SDK
  experiment schemas; and
- removes the hard requirement for the presence of the
  firefoxLabsDescriptionLinks field in order to align the validation
  behaviour between the Pydantic model and the generated JSON schema.

Fixes #15865

Author: freshstrangemusic

schemas/index.d.ts

@@ -153,23 +153,15 @@ export interface DesktopAllVersionsNimbusExperiment {
    */
   publishedDate?: string | null;
   /**
-   * Branch configuration for the experiment.
-   */
-  branches: DesktopAllVersionsExperimentBranch[];
-  /**
-   * When this property is set to true, treat this experiment as aFirefox Labs experiment
+   * When this property is set to true, treat this experiment as a Firefox Labs experiment
    */
   isFirefoxLabsOptIn?: boolean;
   /**
-   * The group this should appear under in Firefox Labs
-   */
-  firefoxLabsGroup?: string | null;
-  /**
-   * The title shown in Firefox Labs (Fluent ID)
+   * The title shown in Firefox Labs (Fluent ID or Resource ID)
    */
   firefoxLabsTitle?: string | null;
   /**
-   * The description shown in Firefox Labs (Fluent ID)
+   * The description shown in Firefox Labs (Fluent ID or Resource ID)
    */
   firefoxLabsDescription?: string | null;
   /**
@@ -178,16 +170,24 @@ export interface DesktopAllVersionsNimbusExperiment {
   firefoxLabsDescriptionLinks?: {
     [k: string]: string;
   } | null;
-  /**
-   * Opt out of feature schema validation.
-   */
-  featureValidationOptOut?: boolean;
   /**
    * Does the experiment require a restart to take effect?
    *
    * Only used by Firefox Labs Opt-Ins.
    */
   requiresRestart?: boolean;
+  /**
+   * Branch configuration for the experiment.
+   */
+  branches: DesktopAllVersionsExperimentBranch[];
+  /**
+   * Opt out of feature schema validation.
+   */
+  featureValidationOptOut?: boolean;
+  /**
+   * The group this should appear under in Firefox Labs
+   */
+  firefoxLabsGroup?: string | null;
 }
 export interface ExperimentBucketConfig {
   randomizationUnit: RandomizationUnit;
@@ -399,23 +399,15 @@ export interface DesktopNimbusExperiment {
    */
   publishedDate?: string | null;
   /**
-   * Branch configuration for the experiment.
-   */
-  branches: DesktopExperimentBranch[];
-  /**
-   * When this property is set to true, treat this experiment as aFirefox Labs experiment
+   * When this property is set to true, treat this experiment as a Firefox Labs experiment
    */
   isFirefoxLabsOptIn?: boolean;
   /**
-   * The group this should appear under in Firefox Labs
-   */
-  firefoxLabsGroup?: string | null;
-  /**
-   * The title shown in Firefox Labs (Fluent ID)
+   * The title shown in Firefox Labs (Fluent ID or Resource ID)
    */
   firefoxLabsTitle?: string | null;
   /**
-   * The description shown in Firefox Labs (Fluent ID)
+   * The description shown in Firefox Labs (Fluent ID or Resource ID)
    */
   firefoxLabsDescription?: string | null;
   /**
@@ -424,16 +416,24 @@ export interface DesktopNimbusExperiment {
   firefoxLabsDescriptionLinks?: {
     [k: string]: string;
   } | null;
-  /**
-   * Opt out of feature schema validation.
-   */
-  featureValidationOptOut?: boolean;
   /**
    * Does the experiment require a restart to take effect?
    *
    * Only used by Firefox Labs Opt-Ins.
    */
   requiresRestart?: boolean;
+  /**
+   * Branch configuration for the experiment.
+   */
+  branches: DesktopExperimentBranch[];
+  /**
+   * Opt out of feature schema validation.
+   */
+  featureValidationOptOut?: boolean;
+  /**
+   * The group this should appear under in Firefox Labs
+   */
+  firefoxLabsGroup?: string | null;
 }
 /**
  * The branch definition supported on Firefox Desktop 95+.
@@ -577,6 +577,30 @@ export interface SdkNimbusExperiment {
    * If null, it has not yet been published.
    */
   publishedDate?: string | null;
+  /**
+   * When this property is set to true, treat this experiment as a Firefox Labs experiment
+   */
+  isFirefoxLabsOptIn?: boolean;
+  /**
+   * The title shown in Firefox Labs (Fluent ID or Resource ID)
+   */
+  firefoxLabsTitle?: string | null;
+  /**
+   * The description shown in Firefox Labs (Fluent ID or Resource ID)
+   */
+  firefoxLabsDescription?: string | null;
+  /**
+   * Links that will be used with the firefoxLabsDescription Fluent ID. May be null for Firefox Labs Opt-In recipes that do not use links.
+   */
+  firefoxLabsDescriptionLinks?: {
+    [k: string]: string;
+  } | null;
+  /**
+   * Does the experiment require a restart to take effect?
+   *
+   * Only used by Firefox Labs Opt-Ins.
+   */
+  requiresRestart?: boolean;
   /**
    * Branch configuration for the SDK experiment.
    */

schemas/mozilla_nimbus_schemas/experimenter_apis/common.py

@@ -2,8 +2,9 @@
 from enum import Enum
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, RootModel
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, RootModel, model_validator
 from pydantic.json_schema import SkipJsonSchema
+from typing_extensions import Self
 
 
 class RandomizationUnit(str, Enum):
@@ -26,9 +27,7 @@ class ExperimentBucketConfig(BaseModel):
     count: int = Field(description="Number of buckets in the range.")
     total: int = Field(
         description=(
-            "The total number of buckets.\n"
-            "\n"
-            "You can assume this will always be 10000."
+            "The total number of buckets.\n\nYou can assume this will always be 10000."
         )
     )
 
@@ -225,4 +224,73 @@ class BaseExperiment(BaseModel):
         default=None,
     )
 
-    model_config = ConfigDict(use_enum_values=True)
+    # Firefox Labs-related fields.
+
+    isFirefoxLabsOptIn: bool = Field(
+        description=(
+            "When this property is set to true, treat this experiment as a "
+            "Firefox Labs experiment"
+        ),
+        default=None,
+    )
+    firefoxLabsTitle: str | None = Field(
+        description="The title shown in Firefox Labs (Fluent ID or Resource ID)",
+        default=None,
+    )
+    firefoxLabsDescription: str | None = Field(
+        description="The description shown in Firefox Labs (Fluent ID or Resource ID)",
+        default=None,
+    )
+    firefoxLabsDescriptionLinks: dict[str, HttpUrl] | None = Field(
+        description=(
+            "Links that will be used with the firefoxLabsDescription Fluent ID. May be "
+            "null for Firefox Labs Opt-In recipes that do not use links."
+        ),
+        default=None,
+    )
+    requiresRestart: bool | SkipJsonSchema[None] = Field(
+        description=(
+            "Does the experiment require a restart to take effect?\n"
+            "\n"
+            "Only used by Firefox Labs Opt-Ins."
+        ),
+        default=False,
+    )
+
+    @model_validator(mode="after")
+    @classmethod
+    def validate_firefox_labs_base(cls, data: Self) -> Self:
+        if data.isFirefoxLabsOptIn:
+            if data.firefoxLabsTitle is None:
+                raise ValueError(
+                    "missing field firefoxLabsTitle (required because isFirefoxLabsOptIn "
+                    "is True)"
+                )
+            if data.firefoxLabsDescription is None:
+                raise ValueError(
+                    "missing field firefoxLabsDescription (required because "
+                    "isFirefoxLabsOptIn is True)"
+                )
+
+        return data
+
+    model_config = ConfigDict(
+        use_enum_values=True,
+        json_schema_extra={
+            "dependentSchemas": {
+                "isFirefoxLabsOptIn": {
+                    "if": {
+                        "properties": {
+                            "isFirefoxLabsOptIn": {"const": True},
+                        },
+                    },
+                    "then": {
+                        "required": [
+                            "firefoxLabsDescription",
+                            "firefoxLabsTitle",
+                        ],
+                    },
+                }
+            }
+        },
+    )