From 97d79a310600f9fc15c7d10a31ac9b48c05d6a3f Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Fri, 24 Jan 2025 12:10:37 +0100
Subject: [PATCH 01/10] docs(abtests) v3 api

---
 specs/abtesting-v3/common/parameters.yml      | 158 ++++++++++++++++
 specs/abtesting-v3/common/schemas/ABTest.yml  | 170 ++++++++++++++++++
 .../common/schemas/ABTestResponse.yml         |  14 ++
 .../common/schemas/AddABTestsVariant.yml      |  38 ++++
 .../common/schemas/EstimateABTestResponse.yml |  18 ++
 .../common/schemas/ScheduleABTestResponse.yml |   8 +
 specs/abtesting-v3/common/schemas/Variant.yml |  94 ++++++++++
 specs/abtesting-v3/paths/abtest.yml           |  65 +++++++
 specs/abtesting-v3/paths/abtests.yml          | 137 ++++++++++++++
 specs/abtesting-v3/paths/estimate.yml         |  62 +++++++
 specs/abtesting-v3/paths/scheduleABTest.yml   |  58 ++++++
 specs/abtesting-v3/paths/stopABTest.yml       |  35 ++++
 specs/abtesting-v3/spec.yml                   | 109 +++++++++++
 13 files changed, 966 insertions(+)
 create mode 100644 specs/abtesting-v3/common/parameters.yml
 create mode 100644 specs/abtesting-v3/common/schemas/ABTest.yml
 create mode 100644 specs/abtesting-v3/common/schemas/ABTestResponse.yml
 create mode 100644 specs/abtesting-v3/common/schemas/AddABTestsVariant.yml
 create mode 100644 specs/abtesting-v3/common/schemas/EstimateABTestResponse.yml
 create mode 100644 specs/abtesting-v3/common/schemas/ScheduleABTestResponse.yml
 create mode 100644 specs/abtesting-v3/common/schemas/Variant.yml
 create mode 100644 specs/abtesting-v3/paths/abtest.yml
 create mode 100644 specs/abtesting-v3/paths/abtests.yml
 create mode 100644 specs/abtesting-v3/paths/estimate.yml
 create mode 100644 specs/abtesting-v3/paths/scheduleABTest.yml
 create mode 100644 specs/abtesting-v3/paths/stopABTest.yml
 create mode 100644 specs/abtesting-v3/spec.yml

diff --git a/specs/abtesting-v3/common/parameters.yml b/specs/abtesting-v3/common/parameters.yml
new file mode 100644
index 0000000000..1be5a7b976
--- /dev/null
+++ b/specs/abtesting-v3/common/parameters.yml
@@ -0,0 +1,158 @@
+# path
+ID:
+  in: path
+  name: id
+  description: Unique A/B test identifier.
+  required: true
+  schema:
+    $ref: "#/abTestID"
+
+# misc
+index:
+  type: string
+  description: Index name of the A/B test variant (case-sensitive).
+  example: "delcourt_production"
+
+abTestID:
+  type: integer
+  description: Unique A/B test identifier.
+  example: 224
+
+abTestScheduleID:
+  type: integer
+  description: Unique scheduled A/B test identifier.
+  example: 224
+
+endAt:
+  type: string
+  description: End date and time of the A/B test, in RFC 3339 format.
+  example: 2023-06-17T00:00:00Z
+
+createdAt:
+  type: string
+  description: Date and time when the A/B test was created, in RFC 3339 format.
+  example: 2023-06-15T15:06:04.249906Z
+
+updatedAt:
+  type: string
+  description: Date and time when the A/B test was last updated, in RFC 3339 format.
+  example: 2023-06-15T15:06:44.400601Z
+
+scheduledAt:
+  type: string
+  description: Date and time when the A/B test is scheduled to start, in RFC 3339 format.
+  example: 2023-06-15T15:06:44.400601Z
+
+name:
+  type: string
+  description: A/B test name.
+  example: Custom ranking sales rank test
+
+description:
+  type: string
+  description: Description for this variant.
+  example: Current production index
+
+trafficPercentage:
+  type: integer
+  description: Percentage of search requests each variant receives.
+  minimum: 0
+  maximum: 100
+  example: 60
+
+currencies:
+  type: object
+  description: A/B test currencies.
+  example:
+    USD:
+      currency: USD
+      revenue: 120.0
+      mean: 53.7
+      standardDeviation: 12.3
+    EUR:
+      currency: EUR
+      revenue: 100.0
+      mean: 43.7
+      standardDeviation: 10.3
+  additionalProperties:
+    $ref: "#/currency"
+    x-additionalPropertiesName: currency code
+
+currency:
+  type: object
+  properties:
+    currency:
+      type: string
+      description: Currency code.
+      example: "USD"
+    revenue:
+      type: number
+      format: double
+      description: Revenue for this currency.
+      example: 120.0
+    mean:
+      type: number
+      format: double
+      description: Mean for this currency.
+      example: 53.7
+    standardDeviation:
+      type: number
+      format: double
+      description: Standard deviation for this currency.
+      example: 12.3
+
+filterEffects:
+  type: object
+  description: A/B test filter effects resulting from configuration settings.
+  properties:
+    outliers:
+      title: outliersFilter
+      type: object
+      description: Outliers removed from the A/B test as a result of configuration settings.
+      example:
+        usersCount: 1
+        trackedSearchesCount: 237
+      properties:
+        usersCount:
+          type: integer
+          description: Number of users removed from the A/B test.
+          example: 1
+        trackedSearchesCount:
+          type: integer
+          description: Number of tracked searches removed from the A/B test.
+          example: 237
+    emptySearch:
+      title: emptySearchFilter
+      type: object
+      description: Empty searches removed from the A/B test as a result of configuration settings.
+      example:
+        usersCount: 1
+        trackedSearchesCount: 237
+      properties:
+        usersCount:
+          type: integer
+          description: Number of users removed from the A/B test.
+          example: 1
+        trackedSearchesCount:
+          type: integer
+          description: Number of tracked searches removed from the A/B test.
+          example: 237
+
+metric:
+  type: object
+  description: Defines a metric to be retrieved during an A/B test.
+  properties:
+    name:
+      type: string
+      description: Name of the metric.
+    dimension:
+      type: string
+      description: Dimension of the metric, for example, in case of a revenue metric it could be USD, EUR...
+  required:
+    - name
+  example:
+    - name: revenue
+      dimension: USD
+    - name: conversionRate
+    - name: clickThroughRate
+    - name: trackedSearchCount
diff --git a/specs/abtesting-v3/common/schemas/ABTest.yml b/specs/abtesting-v3/common/schemas/ABTest.yml
new file mode 100644
index 0000000000..a769d098a0
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/ABTest.yml
@@ -0,0 +1,170 @@
+ABTests:
+  oneOf:
+    - type: array
+      description: A/B tests.
+      items:
+        $ref: '#/ABTest'
+    - type: 'null'
+      description: No A/B tests are configured for this application.
+
+ABTest:
+  type: object
+  additionalProperties: false
+  properties:
+    abTestID:
+      $ref: '../parameters.yml#/abTestID'
+    clickSignificance:
+      description: |
+        A/B test significance calculated from click events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+        Lower values have a.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    conversionSignificance:
+      description: |
+        A/B test significance calculated from conversion events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    addToCartSignificance:
+      description: |
+        A/B test significance calculated from add-to-cart events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    purchaseSignificance:
+      description: |
+        A/B test significance calculated from purchase events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    revenueSignificance:
+      description: |
+        A/B test significance calculated from revenue data.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: object
+          additionalProperties:
+            type: number
+            format: double
+            x-additionalPropertiesName: currency code
+          example:
+            USD: 1
+            EUR: 0.87
+        - type: 'null'
+    updatedAt:
+      $ref: '../parameters.yml#/updatedAt'
+    createdAt:
+      $ref: '../parameters.yml#/createdAt'
+    endAt:
+      $ref: '../parameters.yml#/endAt'
+    name:
+      $ref: '../parameters.yml#/name'
+    status:
+      $ref: '#/Status'
+    variants:
+      $ref: 'Variant.yml#/variants'
+    configuration:
+      $ref: '#/ABTestConfiguration'
+  required:
+    - status
+    - name
+    - createdAt
+    - endAt
+    - updatedAt
+    - abTestID
+    - variants
+
+Status:
+  type: string
+  description: |
+    A/B test status.
+
+    - `active`. The A/B test is live and search traffic is split between the two variants.
+    - `stopped`. You stopped the A/B test. The A/B test data is still available for analysis.
+    - `expired`. The A/B test was automatically stopped after reaching its end date.
+    - `failed`. Creating the A/B test failed.
+  example: active
+  enum:
+    - active
+    - stopped
+    - expired
+    - failed
+
+ABTestConfiguration:
+  title: configuration
+  type: object
+  description: A/B test configuration.
+  properties:
+    outliers:
+      $ref: '#/Outliers'
+    emptySearch:
+      $ref: '#/EmptySearch'
+    minimumDetectableEffect:
+      $ref: '#/MinimumDetectableEffect'
+
+Outliers:
+  type: object
+  description: Configuration for handling outliers.
+  properties:
+    exclude:
+      type: boolean
+      description: Whether to exclude outliers when calculating A/B test results.
+      default: true
+
+EmptySearch:
+  type: object
+  description: Configuration for handling empty searches.
+  properties:
+    exclude:
+      type: boolean
+      description: Whether to exclude empty searches when calculating A/B test results.
+
+MinimumDetectableEffect:
+  type: object
+  description: Configuration for the smallest difference between test variants you want to detect.
+  properties:
+    size:
+      type: number
+      format: double
+      minimum: 0
+      maximum: 1
+      description: |
+        Smallest difference in an observable metric between variants.
+        For example, to detect a 10% difference between variants, set this value to 0.1.
+    metric:
+      $ref: '#/EffectMetric'
+  required:
+    - size
+    - metric
+
+EffectMetric:
+  type: string
+  description: Metric for which you want to detect the smallest relative difference.
+  enum:
+    - addToCartRate
+    - clickThroughRate
+    - conversionRate
+    - purchaseRate
diff --git a/specs/abtesting-v3/common/schemas/ABTestResponse.yml b/specs/abtesting-v3/common/schemas/ABTestResponse.yml
new file mode 100644
index 0000000000..ed3f5e6d90
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/ABTestResponse.yml
@@ -0,0 +1,14 @@
+ABTestResponse:
+  type: object
+  additionalProperties: false
+  properties:
+    index:
+      $ref: '../parameters.yml#/index'
+    abTestID:
+      $ref: '../parameters.yml#/abTestID'
+    taskID:
+      $ref: '../../../common/responses/common.yml#/taskID'
+  required:
+    - abTestID
+    - index
+    - taskID
diff --git a/specs/abtesting-v3/common/schemas/AddABTestsVariant.yml b/specs/abtesting-v3/common/schemas/AddABTestsVariant.yml
new file mode 100644
index 0000000000..fc14f38024
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/AddABTestsVariant.yml
@@ -0,0 +1,38 @@
+AddABTestsVariant:
+  oneOf:
+    - $ref: '#/abTestsVariant'
+    - $ref: '#/abTestsVariantSearchParams'
+
+abTestsVariantSearchParams:
+  allOf:
+    - $ref: '#/abTestsVariant'
+    - $ref: '#/customSearchParams'
+
+abTestsVariant:
+  type: object
+  additionalProperties: false
+  properties:
+    index:
+      $ref: '../parameters.yml#/index'
+    trafficPercentage:
+      $ref: '../parameters.yml#/trafficPercentage'
+    description:
+      $ref: '../parameters.yml#/description'
+  required:
+    - index
+    - trafficPercentage
+
+customSearchParams:
+  type: object
+  description: |
+    Search parameters to add to the test variant.
+    Only use this parameter if the two variants use the same index.
+  example: {'typoTolerance': false, 'synonyms': false}
+  additionalProperties: false
+  properties:
+    customSearchParameters:
+      type: object
+  required:
+    - customSearchParameters
+  x-discriminator-fields:
+    - customSearchParameters
diff --git a/specs/abtesting-v3/common/schemas/EstimateABTestResponse.yml b/specs/abtesting-v3/common/schemas/EstimateABTestResponse.yml
new file mode 100644
index 0000000000..6d491f24cc
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/EstimateABTestResponse.yml
@@ -0,0 +1,18 @@
+EstimateABTestResponse:
+  type: object
+  properties:
+    durationDays:
+      type: integer
+      format: int64
+      description: Estimated number of days needed to reach the sample sizes required for detecting the configured effect. This value is based on historical traffic.
+      example: 21
+    sampleSizes:
+      type: array
+      description: |
+        Sample size estimates for each variant. The first element is the control variant.
+        Each element is the estimated number of searches required to achieve the desired statistical significance.
+      items:
+        type: integer
+        format: int64
+        description: Number of tracked searches needed to be able to detect the configured effect for the control variant.
+        example: 23415
diff --git a/specs/abtesting-v3/common/schemas/ScheduleABTestResponse.yml b/specs/abtesting-v3/common/schemas/ScheduleABTestResponse.yml
new file mode 100644
index 0000000000..a1278e7b77
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/ScheduleABTestResponse.yml
@@ -0,0 +1,8 @@
+ScheduleABTestResponse:
+  type: object
+  additionalProperties: false
+  properties:
+    abTestScheduleID:
+      $ref: '../parameters.yml#/abTestScheduleID'
+  required:
+    - abTestScheduleID
diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
new file mode 100644
index 0000000000..b4c07a412d
--- /dev/null
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -0,0 +1,94 @@
+variants:
+  type: array
+  description: |
+    A/B test variants.
+
+    The first variant is your _control_ index, typically your production index.
+    All of the additionnal variants are indexes with changed settings that you want to test against the control.
+  items:
+    $ref: "#/variant"
+
+variant:
+  type: object
+  additionalProperties: false
+  properties:
+    description:
+      $ref: "../parameters.yml#/description"
+    estimatedSampleSize:
+      type: integer
+      description: |
+        Estimated number of searches required to achieve the desired statistical significance.
+
+        The A/B test configuration must include a `mininmumDetectableEffect` setting for this number to be included in the response.
+      example: 0
+    filterEffects:
+      $ref: "../parameters.yml#/filterEffects"
+    index:
+      $ref: "../parameters.yml#/index"
+    trafficPercentage:
+      $ref: "../parameters.yml#/trafficPercentage"
+    metrics:
+      $ref: "#/metrics"
+  required:
+    - index
+    - description
+    - trafficPercentage
+    - metrics
+
+metrics:
+  type: array
+  description: All ABTest metrics that were defined during test creation
+  items:
+    $ref: "#/metric"
+
+metric:
+  type: object
+  properties:
+    name:
+      type: string
+    updatedAt:
+      type: string
+      description: Date and time when the metric was last updated, in RFC 3339 format.
+    value:
+      type: number
+      format: double
+    pvalue:
+      type: number
+      format: double
+    dimension:
+      type: string
+      description: Dimension defined during test creation
+    winsorizedValue:
+      type: number
+      format: double
+      description: |
+        Only present in case the metric is a revenue. 
+        It is the normalized value of it. 
+        It is tied to a per revenue-currency pair contrary to other 
+        global filter effects (such as outliers and empty search count).
+  required:
+    - name
+    - updatedAt
+    - value
+    - pvalue
+  example:
+    - name: addToCartCount
+      updatedAt: 2025-06-15T15:06:44.400601Z
+      value: 5
+      pvalue: 0.01
+    - name: clickThroughRate
+      updatedAt: 2025-05-15T17:52:15.644906Z
+      value: 0.20869847452125934
+      pvalue: 0.004
+    - name: revenue
+      dimension: USD
+      updatedAt": 2025-05-15T17:52:15.644906Z
+      value: 1200.50
+      pValue: 0.04
+      winsorizedValue: 1123.45
+    - name: revenue
+      dimension: EUR
+      updatedAt: 2025-05-15T17:52:15.644906Z
+      value: 999.66
+      pValue: 0.04
+      winsorizedValue: 888.44
diff --git a/specs/abtesting-v3/paths/abtest.yml b/specs/abtesting-v3/paths/abtest.yml
new file mode 100644
index 0000000000..1e2bf89611
--- /dev/null
+++ b/specs/abtesting-v3/paths/abtest.yml
@@ -0,0 +1,65 @@
+get:
+  tags:
+    - abtest
+  operationId: getABTest
+  x-acl:
+    - analytics
+  summary: Retrieve A/B test details
+  description: Retrieves the details for an A/B test by its ID.
+  parameters:
+    - $ref: '../common/parameters.yml#/ID'
+  responses:
+    '200':
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
+        x-ratelimit-remaining:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
+        x-ratelimit-reset:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/ABTest.yml#/ABTest'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
+
+delete:
+  tags:
+    - abtest
+  operationId: deleteABTest
+  x-acl:
+    - editSettings
+  summary: Delete an A/B test
+  description: Deletes an A/B test by its ID.
+  parameters:
+    - $ref: '../common/parameters.yml#/ID'
+  responses:
+    '200':
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
+        x-ratelimit-remaining:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
+        x-ratelimit-reset:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/ABTestResponse.yml#/ABTestResponse'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/abtesting-v3/paths/abtests.yml b/specs/abtesting-v3/paths/abtests.yml
new file mode 100644
index 0000000000..c10258234a
--- /dev/null
+++ b/specs/abtesting-v3/paths/abtests.yml
@@ -0,0 +1,137 @@
+post:
+  tags:
+    - abtest
+  operationId: addABTests
+  x-acl:
+    - editSettings
+  summary: Create an A/B test
+  description: Creates a new A/B test.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          title: addABTestsRequest
+          type: object
+          additionalProperties: false
+          properties:
+            name:
+              $ref: "../common/parameters.yml#/name"
+            variants:
+              type: array
+              description: A/B test variants.
+              minItems: 2
+              items:
+                $ref: "../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant"
+            metrics:
+              type: array
+              description: A/B test metrics to retrieve.
+              items:
+                $ref: "../common/parameters.yml#/metric"
+            configuration:
+              $ref: "../common/schemas/ABTest.yml#/ABTestConfiguration"
+            endAt:
+              $ref: "../common/parameters.yml#/endAt"
+          required:
+            - name
+            - variants
+            - metrics
+            - endAt
+  responses:
+    "200":
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-limit"
+        x-ratelimit-remaining:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-remaining"
+        x-ratelimit-reset:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-reset"
+      content:
+        application/json:
+          schema:
+            $ref: "../common/schemas/ABTestResponse.yml#/ABTestResponse"
+    "400":
+      $ref: "../../common/responses/BadRequest.yml"
+    "402":
+      $ref: "../../common/responses/FeatureNotEnabled.yml"
+    "403":
+      $ref: "../../common/responses/MethodNotAllowed.yml"
+    "404":
+      $ref: "../../common/responses/IndexNotFound.yml"
+
+get:
+  tags:
+    - abtest
+  operationId: listABTests
+  x-acl:
+    - analytics
+  summary: List all A/B tests
+  description: Lists all A/B tests you configured for this application.
+  parameters:
+    - name: offset
+      in: query
+      description: Position of the first item to return.
+      required: false
+      schema:
+        type: integer
+        default: 0
+        minimum: 0
+    - name: limit
+      in: query
+      description: Number of items to return.
+      required: false
+      schema:
+        type: integer
+        default: 10
+    - name: indexPrefix
+      in: query
+      description: Index name prefix. Only A/B tests for indices starting with this string are included in the response.
+      example: "dev_"
+      schema:
+        type: string
+    - name: indexSuffix
+      in: query
+      description: Index name suffix. Only A/B tests for indices ending with this string are included in the response.
+      example: "_development"
+      schema:
+        type: string
+  responses:
+    "200":
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-limit"
+        x-ratelimit-remaining:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-remaining"
+        x-ratelimit-reset:
+          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-reset"
+      content:
+        application/json:
+          schema:
+            title: listABTestsResponse
+            type: object
+            additionalProperties: false
+            properties:
+              abtests:
+                $ref: "../common/schemas/ABTest.yml#/ABTests"
+              count:
+                type: integer
+                description: Number of A/B tests.
+                example: 10
+              total:
+                type: integer
+                description: Number of retrievable A/B tests.
+                example: 12
+            required:
+              - abtests
+              - count
+              - total
+    "400":
+      $ref: "../../common/responses/BadRequest.yml"
+    "402":
+      $ref: "../../common/responses/FeatureNotEnabled.yml"
+    "403":
+      $ref: "../../common/responses/MethodNotAllowed.yml"
+    "404":
+      $ref: "../../common/responses/IndexNotFound.yml"
diff --git a/specs/abtesting-v3/paths/estimate.yml b/specs/abtesting-v3/paths/estimate.yml
new file mode 100644
index 0000000000..fa29a90a08
--- /dev/null
+++ b/specs/abtesting-v3/paths/estimate.yml
@@ -0,0 +1,62 @@
+post:
+  tags:
+    - abtest
+  operationId: estimateABTest
+  x-acl:
+    - analytics
+  summary: Estimate the sample size and duration of an A/B test
+  description: Given the traffic percentage and the expected effect size, this endpoint estimates the sample size and duration of an A/B test based on historical traffic.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          title: estimateABTestRequest
+          type: object
+          additionalProperties: false
+          properties:
+            configuration:
+              title: estimateConfiguration
+              type: object
+              description: A/B test configuration for estimating the sample size and duration using minimum detectable effect.
+              properties:
+                outliers:
+                  $ref: '../common/schemas/ABTest.yml#/Outliers'
+                emptySearch:
+                  $ref: '../common/schemas/ABTest.yml#/EmptySearch'
+                minimumDetectableEffect:
+                  $ref: '../common/schemas/ABTest.yml#/MinimumDetectableEffect'
+              required:
+                - minimumDetectableEffect
+            variants:
+              type: array
+              description: A/B test variants.
+              minItems: 2
+              maxItems: 2
+              items:
+                $ref: '../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant'
+          required:
+            - configuration
+            - variants
+  responses:
+    '200':
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
+        x-ratelimit-remaining:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
+        x-ratelimit-reset:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/EstimateABTestResponse.yml#/EstimateABTestResponse'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/abtesting-v3/paths/scheduleABTest.yml b/specs/abtesting-v3/paths/scheduleABTest.yml
new file mode 100644
index 0000000000..3939d4314c
--- /dev/null
+++ b/specs/abtesting-v3/paths/scheduleABTest.yml
@@ -0,0 +1,58 @@
+post:
+  tags:
+    - abtest
+  operationId: scheduleABTest
+  x-acl:
+    - editSettings
+  summary: Schedule an A/B test
+  description: |
+    Schedule an A/B test to be started at a later time.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          title: scheduleABTestsRequest
+          type: object
+          additionalProperties: false
+          properties:
+            name:
+              $ref: '../common/parameters.yml#/name'
+            variants:
+              type: array
+              description: A/B test variants.
+              minItems: 2
+              maxItems: 2
+              items:
+                $ref: '../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant'
+            scheduledAt:
+              $ref: '../common/parameters.yml#/scheduledAt'
+            endAt:
+              $ref: '../common/parameters.yml#/endAt'
+          required:
+            - name
+            - variants
+            - scheduledAt
+            - endAt
+  responses:
+    '200':
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
+        x-ratelimit-remaining:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
+        x-ratelimit-reset:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/ScheduleABTestResponse.yml#/ScheduleABTestResponse'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/abtesting-v3/paths/stopABTest.yml b/specs/abtesting-v3/paths/stopABTest.yml
new file mode 100644
index 0000000000..1542f05339
--- /dev/null
+++ b/specs/abtesting-v3/paths/stopABTest.yml
@@ -0,0 +1,35 @@
+post:
+  tags:
+    - abtest
+  operationId: stopABTest
+  x-acl:
+    - editSettings
+  summary: Stop an A/B test
+  description: |
+    Stops an A/B test by its ID.
+
+    You can't restart stopped A/B tests.
+  parameters:
+    - $ref: '../common/parameters.yml#/ID'
+  responses:
+    '200':
+      description: OK
+      headers:
+        x-ratelimit-limit:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
+        x-ratelimit-remaining:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
+        x-ratelimit-reset:
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/ABTestResponse.yml#/ABTestResponse'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/abtesting-v3/spec.yml b/specs/abtesting-v3/spec.yml
new file mode 100644
index 0000000000..31a92a8bff
--- /dev/null
+++ b/specs/abtesting-v3/spec.yml
@@ -0,0 +1,109 @@
+openapi: 3.0.2
+externalDocs:
+  url: https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/
+  description: |
+    Related guide: A/B testing.
+info:
+  title: A/B Testing API
+  description: |
+    The Algolia A/B Testing API lets you manage your Algolia A/B tests to optimize your search experience.
+
+    ## Base URLs
+
+    The base URLs for requests to the A/B testing API are:
+
+    - `https://analytics.us.algolia.com`
+    - `https://analytics.de.algolia.com`
+    - `https://analytics.algolia.com` (routes requests to the closest of the above servers, based on your geographical location)
+
+    Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).
+
+    **All requests must use HTTPS.**
+
+    ## Availability and authentication
+
+    Access to the A/B testing API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
+
+    To authenticate your API requests, add these headers:
+
+    - `x-algolia-application-id`. Your Algolia application ID.
+    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
+      The required access control list (ACL) to make a request is listed in each endpoint's reference.
+
+    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account).
+
+    ## Rate limits
+
+    You can make up to **100 requests per minute per app** to the A/B testing API.
+    The response includes headers with information about the limits.
+
+    ## Parameters
+
+    Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
+    Non-ASCII characters must be UTF-8 encoded.
+    Plus characters (`+`) are interpreted as spaces.
+
+    ## Response status and errors
+
+    The A/B testing API returns JSON responses.
+    Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
+
+    Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
+    Error responses have a `message` property with more information.
+
+    ## Version
+
+    The current version of the A/B Testing API is version 3, as indicated by the `/3/` in each endpoint's URL.
+  version: 3.0.0
+components:
+  securitySchemes:
+    appId:
+      $ref: "../common/securitySchemes.yml#/appId"
+    apiKey:
+      $ref: "../common/securitySchemes.yml#/apiKey"
+servers:
+  - url: https://analytics.{region}.algolia.com
+    variables:
+      region:
+        enum:
+          - us
+          - de
+        default: us
+  - url: https://analytics.algolia.com
+security:
+  - appId: []
+    apiKey: []
+tags:
+  - name: abtest
+    x-displayName: A/B testing
+    description: |
+      Manage A/B tests.
+
+      A/B tests are configurations one or more indices, usually your production index and an index with different settings that you want to test.
+x-tagGroups:
+  - name: General
+    tags:
+      - abtest
+paths:
+  # ######################
+  # ### Custom request ###
+  # ######################
+  /{path}:
+    $ref: "../common/paths/customRequest.yml"
+
+  /3/abtests:
+    $ref: "paths/abtests.yml"
+  /3/abtests/{id}:
+    $ref: "paths/abtest.yml"
+  /3/abtests/{id}/stop:
+    $ref: "paths/stopABTest.yml"
+  /3/abtests/schedule:
+    $ref: "paths/scheduleABTest.yml"
+  /3/abtests/estimate:
+    $ref: "paths/estimate.yml"
+
+  # ###############
+  # ### Helpers ###
+  # ###############
+  /setClientApiKey:
+    $ref: "../common/helpers/setClientApiKey.yml#/method"

From 21746aeac638d72bffd54fbe03c058fd06e14897 Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:51:26 +0100
Subject: [PATCH 02/10] Update specs/abtesting-v3/common/schemas/Variant.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/common/schemas/Variant.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
index b4c07a412d..474339e613 100644
--- a/specs/abtesting-v3/common/schemas/Variant.yml
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -4,7 +4,7 @@ variants:
     A/B test variants.
 
     The first variant is your _control_ index, typically your production index.
-    All of the additionnal variants are indexes with changed settings that you want to test against the control.
+    All of the additional variants are indexes with changed settings that you want to test against the control.
   items:
     $ref: "#/variant"
 

From 0504af7bec12b0ee09fc1cde53853aa5bb0895cd Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:51:40 +0100
Subject: [PATCH 03/10] Update specs/abtesting-v3/common/schemas/Variant.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/common/schemas/Variant.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
index 474339e613..f155263354 100644
--- a/specs/abtesting-v3/common/schemas/Variant.yml
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -62,7 +62,7 @@ metric:
       type: number
       format: double
       description: |
-        Only present in case the metric is a revenue. 
+        Only present in case the metric is 'revenue'. 
         It is the normalized value of it. 
         It is tied to a per revenue-currency pair contrary to other 
         global filter effects (such as outliers and empty search count).

From c2edc406893e9d104cfb435e1666683c6b8df52d Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:51:50 +0100
Subject: [PATCH 04/10] Update specs/abtesting-v3/common/schemas/Variant.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/common/schemas/Variant.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
index f155263354..87774d27f9 100644
--- a/specs/abtesting-v3/common/schemas/Variant.yml
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -63,7 +63,7 @@ metric:
       format: double
       description: |
         Only present in case the metric is 'revenue'. 
-        It is the normalized value of it. 
+        It is the amount exceeding the 95th percentile of global revenue transactions involved in the AB Test. This amount is not considered when calculating statistical significance.
         It is tied to a per revenue-currency pair contrary to other 
         global filter effects (such as outliers and empty search count).
   required:

From e12b82c1360fd0e917c3dc5908a1741c2545de7e Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:52:15 +0100
Subject: [PATCH 05/10] Update specs/abtesting-v3/paths/abtests.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/paths/abtests.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/abtesting-v3/paths/abtests.yml b/specs/abtesting-v3/paths/abtests.yml
index c10258234a..dcf14bd1df 100644
--- a/specs/abtesting-v3/paths/abtests.yml
+++ b/specs/abtesting-v3/paths/abtests.yml
@@ -25,7 +25,7 @@ post:
                 $ref: "../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant"
             metrics:
               type: array
-              description: A/B test metrics to retrieve.
+              description: A/B test metrics involved in the test. Only these metrics will be considered when calculating results. 
               items:
                 $ref: "../common/parameters.yml#/metric"
             configuration:

From 4083d74579a46b8c03bceb91a1f4aecc1d3e66fb Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:52:35 +0100
Subject: [PATCH 06/10] Update specs/abtesting-v3/paths/scheduleABTest.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/paths/scheduleABTest.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/specs/abtesting-v3/paths/scheduleABTest.yml b/specs/abtesting-v3/paths/scheduleABTest.yml
index 3939d4314c..dbceed987b 100644
--- a/specs/abtesting-v3/paths/scheduleABTest.yml
+++ b/specs/abtesting-v3/paths/scheduleABTest.yml
@@ -22,7 +22,6 @@ post:
               type: array
               description: A/B test variants.
               minItems: 2
-              maxItems: 2
               items:
                 $ref: '../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant'
             scheduledAt:

From c8c5ce36410aacb09042cc209ea68c9ddcdf9e84 Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 14:52:44 +0100
Subject: [PATCH 07/10] Update specs/abtesting-v3/paths/estimate.yml

Co-authored-by: Christopher Hawke <69921547+cdhawke@users.noreply.github.com>
---
 specs/abtesting-v3/paths/estimate.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/specs/abtesting-v3/paths/estimate.yml b/specs/abtesting-v3/paths/estimate.yml
index fa29a90a08..1869ee5a56 100644
--- a/specs/abtesting-v3/paths/estimate.yml
+++ b/specs/abtesting-v3/paths/estimate.yml
@@ -32,7 +32,6 @@ post:
               type: array
               description: A/B test variants.
               minItems: 2
-              maxItems: 2
               items:
                 $ref: '../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant'
           required:

From e3a544e64f0c5070ed0f479ce10b64931b6b93f9 Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 15:49:11 +0100
Subject: [PATCH 08/10] fix(abtests) remove significance from abtest

---
 specs/abtesting-v3/common/schemas/ABTest.yml | 89 +++-----------------
 1 file changed, 14 insertions(+), 75 deletions(-)

diff --git a/specs/abtesting-v3/common/schemas/ABTest.yml b/specs/abtesting-v3/common/schemas/ABTest.yml
index a769d098a0..a967d23e98 100644
--- a/specs/abtesting-v3/common/schemas/ABTest.yml
+++ b/specs/abtesting-v3/common/schemas/ABTest.yml
@@ -3,8 +3,8 @@ ABTests:
     - type: array
       description: A/B tests.
       items:
-        $ref: '#/ABTest'
-    - type: 'null'
+        $ref: "#/ABTest"
+    - type: "null"
       description: No A/B tests are configured for this application.
 
 ABTest:
@@ -12,82 +12,21 @@ ABTest:
   additionalProperties: false
   properties:
     abTestID:
-      $ref: '../parameters.yml#/abTestID'
-    clickSignificance:
-      description: |
-        A/B test significance calculated from click events.
-
-        Values of 0.95 or higher can be considered significant,
-        that is, the difference between A and B variants is _not_ due to random variations.
-        Lower values have a.
-      oneOf:
-        - type: number
-          format: double
-          example: 1
-        - type: 'null'
-    conversionSignificance:
-      description: |
-        A/B test significance calculated from conversion events.
-
-        Values of 0.95 or higher can be considered significant,
-        that is, the difference between A and B variants is _not_ due to random variations.
-      oneOf:
-        - type: number
-          format: double
-          example: 1
-        - type: 'null'
-    addToCartSignificance:
-      description: |
-        A/B test significance calculated from add-to-cart events.
-
-        Values of 0.95 or higher can be considered significant,
-        that is, the difference between A and B variants is _not_ due to random variations.
-      oneOf:
-        - type: number
-          format: double
-          example: 1
-        - type: 'null'
-    purchaseSignificance:
-      description: |
-        A/B test significance calculated from purchase events.
-
-        Values of 0.95 or higher can be considered significant,
-        that is, the difference between A and B variants is _not_ due to random variations.
-      oneOf:
-        - type: number
-          format: double
-          example: 1
-        - type: 'null'
-    revenueSignificance:
-      description: |
-        A/B test significance calculated from revenue data.
-
-        Values of 0.95 or higher can be considered significant,
-        that is, the difference between A and B variants is _not_ due to random variations.
-      oneOf:
-        - type: object
-          additionalProperties:
-            type: number
-            format: double
-            x-additionalPropertiesName: currency code
-          example:
-            USD: 1
-            EUR: 0.87
-        - type: 'null'
+      $ref: "../parameters.yml#/abTestID"
     updatedAt:
-      $ref: '../parameters.yml#/updatedAt'
+      $ref: "../parameters.yml#/updatedAt"
     createdAt:
-      $ref: '../parameters.yml#/createdAt'
+      $ref: "../parameters.yml#/createdAt"
     endAt:
-      $ref: '../parameters.yml#/endAt'
+      $ref: "../parameters.yml#/endAt"
     name:
-      $ref: '../parameters.yml#/name'
+      $ref: "../parameters.yml#/name"
     status:
-      $ref: '#/Status'
+      $ref: "#/Status"
     variants:
-      $ref: 'Variant.yml#/variants'
+      $ref: "Variant.yml#/variants"
     configuration:
-      $ref: '#/ABTestConfiguration'
+      $ref: "#/ABTestConfiguration"
   required:
     - status
     - name
@@ -119,11 +58,11 @@ ABTestConfiguration:
   description: A/B test configuration.
   properties:
     outliers:
-      $ref: '#/Outliers'
+      $ref: "#/Outliers"
     emptySearch:
-      $ref: '#/EmptySearch'
+      $ref: "#/EmptySearch"
     minimumDetectableEffect:
-      $ref: '#/MinimumDetectableEffect'
+      $ref: "#/MinimumDetectableEffect"
 
 Outliers:
   type: object
@@ -155,7 +94,7 @@ MinimumDetectableEffect:
         Smallest difference in an observable metric between variants.
         For example, to detect a 10% difference between variants, set this value to 0.1.
     metric:
-      $ref: '#/EffectMetric'
+      $ref: "#/EffectMetric"
   required:
     - size
     - metric

From e6461d4c706ba8dd6ddfb0b134598e4555825ebf Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 16:31:38 +0100
Subject: [PATCH 09/10] feat(abtests) move filterEffects in metadata + add
 description to pValue

---
 specs/abtesting-v3/common/schemas/Variant.yml | 24 ++++++++++++-------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
index 87774d27f9..ef6dc6d460 100644
--- a/specs/abtesting-v3/common/schemas/Variant.yml
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -21,14 +21,15 @@ variant:
 
         The A/B test configuration must include a `mininmumDetectableEffect` setting for this number to be included in the response.
       example: 0
-    filterEffects:
-      $ref: "../parameters.yml#/filterEffects"
     index:
       $ref: "../parameters.yml#/index"
     trafficPercentage:
       $ref: "../parameters.yml#/trafficPercentage"
     metrics:
       $ref: "#/metrics"
+    metadata:
+      $ref: "#/metadata"
+
   required:
     - index
     - description
@@ -52,9 +53,10 @@ metric:
     value:
       type: number
       format: double
-    pvalue:
+    pValue:
       type: number
       format: double
+      description: PValue for the first variant (control) will always be 0. For the other variants, pValue is calculated for the current variant based on the control.
     dimension:
       type: string
       description: Dimension defined during test creation
@@ -70,25 +72,31 @@ metric:
     - name
     - updatedAt
     - value
-    - pvalue
+    - pValue
   example:
     - name: addToCartCount
       updatedAt: 2025-06-15T15:06:44.400601Z
       value: 5
-      pvalue: 0.01
+      pValue: 0.01
     - name: clickThroughRate
       updatedAt: 2025-05-15T17:52:15.644906Z
       value: 0.20869847452125934
-      pvalue: 0.004
+      pValue: 0.004
     - name: revenue
       dimension: USD
       updatedAt": 2025-05-15T17:52:15.644906Z
       value: 1200.50
       pValue: 0.04
-      winsorizedValue: 1123.45
+      example: 20.2
     - name: revenue
       dimension: EUR
       updatedAt: 2025-05-15T17:52:15.644906Z
       value: 999.66
       pValue: 0.04
-      winsorizedValue: 888.44
+      example: 888.44
+
+metadata:
+  type: object
+  properties:
+    filterEffects:
+      $ref: "../parameters.yml#/filterEffects"

From 24f8eef0baa09ef11ef73771b1ff9d498b5d5771 Mon Sep 17 00:00:00 2001
From: My Lan Aragon <mylan.aragon@algolia.com>
Date: Tue, 28 Jan 2025 17:00:43 +0100
Subject: [PATCH 10/10] feat(abtests) add metadata into metric

---
 specs/abtesting-v3/common/schemas/Variant.yml | 36 ++++++++++++-------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/specs/abtesting-v3/common/schemas/Variant.yml b/specs/abtesting-v3/common/schemas/Variant.yml
index ef6dc6d460..9f5202fc7f 100644
--- a/specs/abtesting-v3/common/schemas/Variant.yml
+++ b/specs/abtesting-v3/common/schemas/Variant.yml
@@ -28,7 +28,7 @@ variant:
     metrics:
       $ref: "#/metrics"
     metadata:
-      $ref: "#/metadata"
+      $ref: "#/variantMetadata"
 
   required:
     - index
@@ -60,14 +60,8 @@ metric:
     dimension:
       type: string
       description: Dimension defined during test creation
-    winsorizedValue:
-      type: number
-      format: double
-      description: |
-        Only present in case the metric is 'revenue'. 
-        It is the amount exceeding the 95th percentile of global revenue transactions involved in the AB Test. This amount is not considered when calculating statistical significance.
-        It is tied to a per revenue-currency pair contrary to other 
-        global filter effects (such as outliers and empty search count).
+    metadata:
+      $ref: "#/metricMetadata"
   required:
     - name
     - updatedAt
@@ -84,19 +78,35 @@ metric:
       pValue: 0.004
     - name: revenue
       dimension: USD
-      updatedAt": 2025-05-15T17:52:15.644906Z
+      updatedAt: 2025-05-15T17:52:15.644906Z
       value: 1200.50
       pValue: 0.04
-      example: 20.2
+      metadata: { "winsorizedValue": 80.2 }
     - name: revenue
       dimension: EUR
       updatedAt: 2025-05-15T17:52:15.644906Z
       value: 999.66
       pValue: 0.04
-      example: 888.44
+      metadata: { "winsorizedValue": 888.8 }
 
-metadata:
+variantMetadata:
   type: object
+  description: Variant specific metadata
   properties:
     filterEffects:
       $ref: "../parameters.yml#/filterEffects"
+
+metricMetadata:
+  type: object
+  description: Metric specific metadata
+  properties:
+    winsorizedValue:
+      type: number
+      format: double
+      description: |
+        Only present in case the metric is 'revenue'. 
+        It is the amount exceeding the 95th percentile of global revenue transactions involved in the AB Test. This amount is not considered when calculating statistical significance.
+        It is tied to a per revenue-currency pair contrary to other 
+        global filter effects (such as outliers and empty search count).
+  example:
+    winsorizedValue: 888.80