summaryrefslogtreecommitdiffstats
path: root/toolkit/components/nimbus/schemas/NimbusExperiment.schema.json
blob: 0514c77399a971ceb7aa3a60d6dd484bb1df7bb4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/NimbusExperiment",
  "definitions": {
    "NimbusExperiment": {
      "type": "object",
      "properties": {
        "schemaVersion": {
          "type": "string",
          "description": "Version of the NimbusExperiment schema this experiment refers to"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier for the experiment"
        },
        "id": {
          "type": "string",
          "description": "Unique identifier for the experiment. This is a duplicate of slug, but is a required field for all Remote Settings records."
        },
        "appName": {
          "type": "string",
          "description": "A slug identifying the targeted product for this experiment. It should be a lowercase_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\" or \"firefox_desktop\"."
        },
        "appId": {
          "type": "string",
          "description": "The platform identifier for the targeted app. The app's identifier exactly as it appears in the relevant app store listing (for relevant platforms) or in the app's Glean initialization call (for other platforms). Examples are \"org.mozilla.firefox_beta\" or \"firefox-desktop\"."
        },
        "channel": {
          "type": "string",
          "description": "A specific channel of an application such as \"nightly\", \"beta\", or \"release\""
        },
        "userFacingName": {
          "type": "string",
          "description": "Public name of the experiment displayed on \"about:studies\""
        },
        "userFacingDescription": {
          "type": "string",
          "description": "Short public description of the experiment displayed on on \"about:studies\""
        },
        "isEnrollmentPaused": {
          "type": "boolean",
          "description": "When this property is set to true, the the SDK should not enroll new users into the experiment that have not already been enrolled."
        },
        "isRollout": {
          "type": "boolean",
          "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"
        },
        "bucketConfig": {
          "type": "object",
          "properties": {
            "randomizationUnit": {
              "type": "string",
              "description": "A unique, stable identifier for the user used as an input to bucket hashing"
            },
            "namespace": {
              "type": "string",
              "description": "Additional inputs to the hashing function"
            },
            "start": {
              "type": "integer",
              "description": "Index of start of the range of buckets"
            },
            "count": {
              "type": "integer",
              "description": "Number of buckets to check"
            },
            "total": {
              "type": "integer",
              "description": "Total number of buckets. You can assume this will always be 10000.",
              "default": 10000
            }
          },
          "required": [
            "randomizationUnit",
            "namespace",
            "start",
            "count",
            "total"
          ],
          "description": "Bucketing configuration"
        },
        "outcomes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string",
                "description": "Identifier for the outcome"
              },
              "priority": {
                "type": "string",
                "description": "e.g. \"primary\" or \"secondary\""
              }
            },
            "required": [
              "slug",
              "priority"
            ]
          },
          "description": "A list of outcomes relevant to the experiment analysis."
        },
        "featureIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of featureIds the experiment contains configurations for."
        },
        "branches": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "Identifier for the branch"
                  },
                  "ratio": {
                    "type": "integer",
                    "description": "Relative ratio of population for the branch (e.g. if branch A=1 and branch B=3, branch A would get 25% of the population)",
                    "default": 1
                  },
                  "feature": {
                    "type": "object",
                    "properties": {
                      "featureId": {
                        "type": "string",
                        "description": "The identifier for the feature flag"
                      },
                      "value": {
                        "type": "object",
                        "additionalProperties": {},
                        "description": "Optional extra params for the feature (this should be validated against a schema)"
                      }
                    },
                    "required": [
                      "featureId",
                      "value"
                    ],
                    "description": "A single feature configuration"
                  }
                },
                "required": [
                  "slug",
                  "ratio",
                  "feature"
                ]
              }
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "Identifier for the branch"
                  },
                  "ratio": {
                    "type": "integer",
                    "description": "Relative ratio of population for the branch (e.g. if branch A=1 and branch B=3, branch A would get 25% of the population)",
                    "default": 1
                  },
                  "feature": {
                    "type": "object",
                    "properties": {
                      "featureId": {
                        "type": "string",
                        "const": "unused-feature-id-for-legacy-support"
                      },
                      "enabled": {
                        "type": "boolean",
                        "const": false
                      },
                      "value": {
                        "type": "object",
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "featureId",
                      "enabled",
                      "value"
                    ],
                    "description": "The feature key must be provided with valid values to prevent crashes if the DTO is encountered by Desktop clients earlier than version 95."
                  },
                  "features": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "featureId": {
                          "type": "string",
                          "description": "The identifier for the feature flag"
                        },
                        "value": {
                          "type": "object",
                          "additionalProperties": {},
                          "description": "Optional extra params for the feature (this should be validated against a schema)"
                        }
                      },
                      "required": [
                        "featureId",
                        "value"
                      ]
                    },
                    "description": "An array of feature configurations"
                  }
                },
                "required": [
                  "slug",
                  "ratio",
                  "feature",
                  "features"
                ]
              }
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "Identifier for the branch"
                  },
                  "ratio": {
                    "type": "integer",
                    "description": "Relative ratio of population for the branch (e.g. if branch A=1 and branch B=3, branch A would get 25% of the population)",
                    "default": 1
                  },
                  "features": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "featureId": {
                          "type": "string",
                          "description": "The identifier for the feature flag"
                        },
                        "value": {
                          "type": "object",
                          "additionalProperties": {},
                          "description": "Optional extra params for the feature (this should be validated against a schema)"
                        }
                      },
                      "required": [
                        "featureId",
                        "value"
                      ]
                    },
                    "description": "An array of feature configurations"
                  }
                },
                "required": [
                  "slug",
                  "ratio",
                  "features"
                ]
              }
            }
          ],
          "description": "Branch configuration for the experiment"
        },
        "targeting": {
          "type": [
            "string",
            "null"
          ],
          "description": "JEXL expression used to filter experiments based on locale, geo, etc."
        },
        "startDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "Actual publish date of the experiment Note that this value is expected to be null in Remote Settings.",
          "format": "date"
        },
        "enrollmentEndDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "Actual enrollment end date of the experiment. Note that this value is expected to be null in Remote Settings.",
          "format": "date"
        },
        "endDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "Actual end date of the experiment. Note that this value is expected to be null in Remote Settings.",
          "format": "date"
        },
        "proposedDuration": {
          "type": "integer",
          "description": "Duration of the experiment from the start date in days. Note that this property is only used during the analysis phase (not by the SDK)"
        },
        "proposedEnrollment": {
          "type": "integer",
          "description": "This represents the number of days that we expect to enroll new users. Note that this property is only used during the analysis phase (not by the SDK)"
        },
        "referenceBranch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The slug of the reference branch (that is, which branch we consider \"control\")"
        },
        "featureValidationOptOut": {
          "type": "boolean",
          "description": "Opt out of feature schema validation. Only supported on desktop."
        },
        "localizations": {
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Per-locale localization substitutions.\n\nThe top level key is the locale (e.g., \"en-US\" or \"fr\"). Each entry is a mapping of string IDs to their localized equivalents.\n\nOnly supported on desktop."
        },
        "locales": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "The list of locale codes (e.g., \"en-US\" or \"fr\") that this experiment is targeting.\n\nIf null, all locales are targeted."
        },
        "publishedDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date that this experiment was first published to Remote Settings. Note that this value is expected to be present in Remote Settings.\n\nIf null, it has not yet been published.",
          "format": "date-time"
        }
      },
      "required": [
        "schemaVersion",
        "slug",
        "id",
        "appName",
        "appId",
        "channel",
        "userFacingName",
        "userFacingDescription",
        "isEnrollmentPaused",
        "bucketConfig",
        "branches",
        "startDate",
        "endDate",
        "proposedEnrollment",
        "referenceBranch"
      ],
      "description": "The experiment definition accessible to: 1. The Nimbus SDK via Remote Settings 2. Jetstream via the Experimenter API"
    }
  }
}