@shipeasy/openapi 2.2.0 → 2.4.0

package/spec/components/schemas/experiment-api-row.yaml

@@ -0,0 +1,293 @@
+# The single wire shape for an experiment row, shared by `ListExperimentsResponse`
+# (`data[]` items) and `GET /api/admin/experiments/{id}`. The app projects every
+# experiment through one `toExperimentApiRow` allow-list at the HTTP boundary, so
+# both endpoints return the SAME object — this schema is that allow-list.
+#
+# Two tiers of fields:
+#   • base (always present) — persisted columns + the pool-slice / headroom /
+#     version fields the serializer defaults (`?? null` / `?? 0` / `?? 1`), so
+#     they appear on every row. These are `required`.
+#   • enriched (list only) — verdict + goal/guardrail summary + exposure spark +
+#     resolved creator/editor emails. The list handler derives them for every
+#     row; the by-id handler returns the raw row, so they are `undefined` and
+#     drop out of the JSON. They are therefore OPTIONAL (present on list rows,
+#     absent on the by-id detail) — never `required`.
+ExperimentApiRow:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque experiment id (`exp_…`).
+    name:
+      type: string
+      maxLength: 128
+      pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
+      description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+    hypothesis:
+      anyOf:
+        - type: string
+        - type: "null"
+    tag:
+      anyOf:
+        - type: string
+        - type: "null"
+    ownerEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+    audience:
+      anyOf:
+        - type: string
+        - type: "null"
+    bucketBy:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 128
+          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
+          description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
+        - type: "null"
+    folder:
+      anyOf:
+        - type: string
+        - type: "null"
+    status:
+      type: string
+      enum:
+        - draft
+        - running
+        - stopped
+        - archived
+    universe:
+      type: string
+      description: Universe name this experiment draws from.
+    targetingGate:
+      anyOf:
+        - type: string
+        - type: "null"
+    holdoutGate:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Per-experiment holdout gate name (a `holdout`-type flag), or `null`.
+    allocationPct:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Allocation in basis points (0–10000).
+    reservedHeadroom:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: Basis points of the split reserved for appended variants (group weights sum to 10000 − this).
+    hashVersion:
+      type: integer
+      minimum: 1
+      description: Bucketing hash algorithm version for the experiment's pool slice (§B4). Defaults to 1.
+    poolOffsetBp:
+      anyOf:
+        - type: integer
+          minimum: 0
+          maximum: 10000
+        - type: "null"
+      description: Basis-point offset of the experiment's contiguous slice in the universe pool, or `null` before a slice is allocated.
+    poolSizeBp:
+      anyOf:
+        - type: integer
+          minimum: 0
+          maximum: 10000
+        - type: "null"
+      description: Basis-point width of the experiment's pool slice (equal to its allocation), or `null` before a slice is allocated.
+    salt:
+      type: string
+    params:
+      type: object
+      additionalProperties:
+        type: string
+        enum:
+          - string
+          - bool
+          - number
+    groups:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
+          weight:
+            type: integer
+            minimum: 0
+            maximum: 10000
+            description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+          params:
+            default: {}
+            description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+            type: object
+            additionalProperties: {}
+        required:
+          - name
+          - weight
+        additionalProperties: false
+        description: One variant in the experiment. Weights across all groups must sum to 10000.
+    significanceThreshold:
+      type: number
+    minRuntimeDays:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+    minSampleSize:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+    sequentialTesting:
+      type: boolean
+    startedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
+    stoppedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+    updatedAt:
+      type: string
+    version:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: Save counter (number of published edits), or `null` on pre-versioning rows.
+    creatorEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Resolved creator email (`created_by` → users). Enriched field: present on list rows, omitted from the by-id detail."
+    updaterEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Resolved last-editor email (`updated_by` → users). Enriched field: present on list rows, omitted from the by-id detail."
+    verdict:
+      type: string
+      enum:
+        - ship
+        - hold
+        - wait
+        - invalid
+        - draft
+      description: "Answer-first decision from the goal metric + guardrails + SRM vs. the significance threshold and min runtime: `ship`, `hold`, `wait`, `invalid`, `draft`. Enriched field: list rows only."
+    verdictTitle:
+      type: string
+      description: "Expanded verdict headline the results hero renders. Enriched field: list rows only."
+    verdictWhy:
+      type: string
+      description: "Verdict rationale the results hero renders. Enriched field: list rows only."
+    goalMetric:
+      anyOf:
+        - type: object
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+          required:
+            - id
+            - name
+          additionalProperties: false
+        - type: "null"
+      description: "The experiment's goal metric `{ id, name }`, or `null` when none is set. Enriched field: list rows only."
+    guardrails:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          name:
+            type: string
+          eventName:
+            anyOf:
+              - type: string
+              - type: "null"
+        required:
+          - id
+          - name
+        additionalProperties: false
+      description: "Guardrail metrics `{ id, name, eventName? }`. Enriched field: list rows only."
+    guardrailCount:
+      type: integer
+      minimum: 0
+      description: "Number of guardrail metrics. Enriched field: list rows only."
+    primaryLiftPct:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: "Goal-metric lift of the leading variant vs. control, in percent, or `null` when not yet computed. Enriched field: list rows only."
+    significancePct:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: "Statistical significance (1 − p) as a percent, or `null` when not yet computed. Enriched field: list rows only."
+    sampleSize:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: "Total distinct units analysed, or `null` when not yet computed. Enriched field: list rows only."
+    exposure:
+      type: array
+      items:
+        type: object
+        properties:
+          ds:
+            type: string
+          value:
+            type: number
+        required:
+          - ds
+          - value
+        additionalProperties: false
+      description: "Cumulative unique-users-enrolled series for the exposure sparkline. Enriched field: list rows only."
+    exposureTotal:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: "Total distinct units ever exposed (sparkline headline), or `null`. Enriched field: list rows only."
+  required:
+    - id
+    - name
+    - description
+    - hypothesis
+    - tag
+    - ownerEmail
+    - audience
+    - bucketBy
+    - folder
+    - status
+    - universe
+    - targetingGate
+    - holdoutGate
+    - allocationPct
+    - reservedHeadroom
+    - hashVersion
+    - poolOffsetBp
+    - poolSizeBp
+    - salt
+    - params
+    - groups
+    - significanceThreshold
+    - minRuntimeDays
+    - minSampleSize
+    - sequentialTesting
+    - startedAt
+    - stoppedAt
+    - updatedAt
+    - version
+  additionalProperties: false