{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-threshold-metric-response-schema.json",
  "title": "Threshold metric",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-metric-api-openapi.yml#/components/schemas/ThresholdMetricResponse",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the metric definition"
    },
    "slug": {
      "type": "string",
      "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")"
    },
    "metricId": {
      "type": "string",
      "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`."
    },
    "variantId": {
      "type": "string",
      "format": "uuid",
      "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config."
    },
    "versionId": {
      "type": "string",
      "format": "uuid",
      "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes."
    },
    "name": {
      "type": "string",
      "description": "Name of the metric"
    },
    "description": {
      "type": "string",
      "description": "Description of what the metric measures"
    },
    "type": {
      "type": "string",
      "enum": [
        "COUNT",
        "NUMERIC",
        "BOOLEAN",
        "SCALE",
        "TEXT",
        "CLASSIFICATION",
        "OFFSET"
      ],
      "description": "Type of value this metric produces"
    },
    "scope": {
      "type": "string",
      "enum": [
        "GLOBAL",
        "PER_PARTICIPANT"
      ],
      "description": "Whether metric is global or per-participant"
    },
    "supportedContexts": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "CALL",
          "SEGMENT",
          "TURN"
        ]
      },
      "description": "Which levels this metric can produce values at"
    },
    "supportedConversationSources": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "enum": [
          "SIMULATED",
          "LIVE"
        ]
      },
      "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations."
    },
    "requiresLiveConversation": {
      "type": "boolean",
      "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards."
    },
    "supportsVariants": {
      "type": "boolean",
      "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403."
    },
    "unit": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the unit"
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ],
          "description": "Symbol for the unit"
        }
      },
      "required": [
        "name",
        "symbol"
      ],
      "description": "Unit information if applicable"
    },
    "evidenceSource": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "metricId": {
          "type": "string",
          "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate"
        },
        "countsWhen": {
          "type": "boolean",
          "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event."
        }
      },
      "required": [
        "metricId",
        "countsWhen"
      ],
      "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence."
    },
    "calculationType": {
      "type": "string",
      "const": "THRESHOLD",
      "description": "Boolean metric derived by comparing a source metric against a threshold."
    },
    "threshold": {
      "$ref": "#/$defs/ThresholdMetricDetails",
      "description": "Threshold configuration."
    }
  },
  "required": [
    "id",
    "slug",
    "metricId",
    "variantId",
    "versionId",
    "name",
    "description",
    "type",
    "scope",
    "supportedContexts",
    "supportedConversationSources",
    "requiresLiveConversation",
    "supportsVariants",
    "evidenceSource",
    "calculationType"
  ],
  "$defs": {
    "ThresholdMetricDetails": {
      "type": "object",
      "properties": {
        "sourceMetricDefinitionId": {
          "type": "string",
          "format": "uuid"
        },
        "operator": {
          "type": "string",
          "enum": [
            "GREATER_THAN",
            "GREATER_THAN_OR_EQUALS",
            "LESS_THAN",
            "LESS_THAN_OR_EQUALS",
            "EQUALS",
            "NOT_EQUALS"
          ]
        },
        "thresholdValue": {
          "type": "string"
        },
        "aggregationMode": {
          "type": "string",
          "enum": [
            "EACH",
            "COUNT",
            "AVERAGE",
            "MIN",
            "MAX",
            "MEDIAN",
            "P95",
            "P99",
            "SUM"
          ]
        },
        "countThreshold": {
          "type": [
            "integer",
            "null"
          ]
        },
        "sourceParticipantRole": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "AGENT",
            "CUSTOMER",
            "SIMULATED_CUSTOMER",
            "BACKGROUND_SPEAKER"
          ]
        },
        "sourceVariantId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        }
      },
      "required": [
        "sourceMetricDefinitionId",
        "operator",
        "thresholdValue",
        "aggregationMode",
        "countThreshold",
        "sourceParticipantRole",
        "sourceVariantId"
      ]
    }
  }
}