{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/joinways-app/json-schema/joinways-app-commercial-analytics-schema.json",
  "title": "CommercialAnalytics",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/joinways-app-openapi.yml#/components/schemas/CommercialAnalytics",
  "allOf": [
    {
      "$ref": "#/$defs/ReportHeader"
    },
    {
      "type": "object",
      "properties": {
        "total_events_created": {
          "type": "integer",
          "description": "Legacy — opportunities created in the period."
        },
        "total_confirmed": {
          "type": "integer",
          "description": "Legacy — of which confirmed."
        },
        "conversion_rate": {
          "type": "integer",
          "description": "Legacy — conversion rate in %, rounded (0 when not computable)."
        },
        "total_revenue_excl_tax": {
          "type": "number",
          "description": "Legacy — revenue signed in the period."
        },
        "total_expected_revenue": {
          "type": "number",
          "description": "Legacy — value of the open pipeline."
        },
        "kpis": {
          "type": "object",
          "properties": {
            "signed_revenue": {
              "$ref": "#/$defs/ReportMetric"
            },
            "signed": {
              "$ref": "#/$defs/ReportMetric"
            },
            "created": {
              "$ref": "#/$defs/ReportMetric"
            },
            "closed": {
              "$ref": "#/$defs/ReportMetric"
            },
            "lost": {
              "$ref": "#/$defs/ReportMetric"
            },
            "cancelled": {
              "$ref": "#/$defs/ReportMetric"
            },
            "transformation_rate": {
              "$ref": "#/$defs/ReportRate"
            },
            "cancellation_rate": {
              "$ref": "#/$defs/ReportRate"
            },
            "average_ticket": {
              "$ref": "#/$defs/ReportMetric"
            },
            "cycle_median_days": {
              "$ref": "#/$defs/ReportMetric"
            }
          }
        },
        "funnel": {
          "type": "object",
          "description": "Inquiries received in the period and what became of them.",
          "properties": {
            "received": {
              "type": "integer"
            },
            "accepted": {
              "type": "integer"
            },
            "quoted": {
              "type": "integer"
            },
            "confirmed": {
              "type": "integer"
            },
            "win_rate": {
              "$ref": "#/$defs/ReportRatio"
            }
          }
        },
        "pipeline": {
          "type": "object",
          "description": "Open options now (not bound to the period).",
          "properties": {
            "open_options": {
              "type": "integer"
            },
            "valued_options": {
              "type": "integer"
            },
            "value": {
              "type": "number"
            },
            "value_from_quotes": {
              "type": "number"
            },
            "weighted_value": {
              "type": [
                "number",
                "null"
              ],
              "description": "Σ value × win probability of the options with a known amount; `null` without enough history (30 options that signed or were lost, at least 5 of each)."
            },
            "scored_options": {
              "type": "integer"
            },
            "history_closed_options": {
              "type": "integer",
              "description": "Options of the last 24 months the win model learns from: closed, or followed open until today (survival model)."
            },
            "global_win_rate_pct": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "monthly": {
          "type": "array",
          "description": "One row per month of the period; `previous_*` is the aligned comparison month.",
          "items": {
            "type": "object",
            "properties": {
              "month": {
                "type": "string"
              },
              "signed_revenue": {
                "type": "number"
              },
              "previous_signed_revenue": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "signed": {
                "type": "integer"
              },
              "previous_signed": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "created": {
                "type": "integer"
              },
              "previous_created": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            }
          }
        },
        "by_venue": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "location_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              {
                "$ref": "#/$defs/SalesGroupRow"
              }
            ]
          }
        },
        "by_source": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "source_key": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string",
                    "description": "Marketing sources are named too (`ads_google` → Google Ads)."
                  }
                }
              },
              {
                "$ref": "#/$defs/SalesGroupRow"
              }
            ]
          }
        },
        "by_owner": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "member_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "dominant_venue": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              {
                "$ref": "#/$defs/SalesGroupRow"
              }
            ]
          }
        },
        "by_type": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string"
                  }
                }
              },
              {
                "$ref": "#/$defs/SalesGroupRow"
              }
            ]
          }
        },
        "loss_reasons": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "reason": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "coverage": {
          "$ref": "#/$defs/ReportCoverage"
        }
      }
    }
  ],
  "$defs": {
    "ReportCoverage": {
      "allOf": [
        {
          "$ref": "#/$defs/ReportRatio"
        },
        {
          "type": "object",
          "description": "Confirmed/signed events with a known amount (`numerator`) out of all of them (`denominator`), and where the amount came from.",
          "properties": {
            "from_event": {
              "type": [
                "integer",
                "null"
              ]
            },
            "from_quote": {
              "type": [
                "integer",
                "null"
              ]
            },
            "from_platform": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        }
      ]
    },
    "ReportHeader": {
      "type": "object",
      "properties": {
        "period": {
          "type": "object",
          "description": "Effective period after defaults and caps.",
          "properties": {
            "from": {
              "type": "string",
              "format": "date"
            },
            "to": {
              "type": "string",
              "format": "date"
            },
            "today": {
              "type": "string",
              "format": "date",
              "description": "Today in the workspace time zone."
            },
            "timezone": {
              "type": "string"
            }
          }
        },
        "comparison": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "year",
                "previous"
              ]
            },
            "from": {
              "type": "string",
              "format": "date"
            },
            "to": {
              "type": "string",
              "format": "date"
            }
          }
        },
        "venue_ids": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Venue filter applied; `null` = all venues."
        },
        "currency": {
          "type": "string",
          "description": "Workspace currency of every amount (amounts are excl. tax, 2 decimals)."
        }
      }
    },
    "ReportMetric": {
      "type": "object",
      "description": "A value for the period and for the comparison period.",
      "properties": {
        "current": {
          "type": [
            "number",
            "null"
          ]
        },
        "previous": {
          "type": [
            "number",
            "null"
          ],
          "description": "Comparison period value; `null` with `compare=none` or when not computable."
        },
        "change_pct": {
          "type": [
            "number",
            "null"
          ],
          "description": "Relative change in % (1 decimal); `null` when `previous` is null or 0."
        }
      }
    },
    "ReportRate": {
      "allOf": [
        {
          "$ref": "#/$defs/ReportRatio"
        },
        {
          "type": "object",
          "properties": {
            "previous_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "change_points": {
              "type": [
                "number",
                "null"
              ],
              "description": "Difference in percentage points with the comparison period."
            }
          }
        }
      ]
    },
    "ReportRatio": {
      "type": "object",
      "description": "A rate with its numerator and denominator.",
      "properties": {
        "pct": {
          "type": [
            "number",
            "null"
          ],
          "description": "0–100, 1 decimal; `null` when the denominator is 0."
        },
        "numerator": {
          "type": "integer"
        },
        "denominator": {
          "type": "integer"
        }
      }
    },
    "SalesGroupRow": {
      "type": "object",
      "properties": {
        "created": {
          "type": "integer",
          "description": "Opportunities created in the period."
        },
        "signed": {
          "type": "integer",
          "description": "Signatures dated in the period."
        },
        "revenue": {
          "type": "number",
          "description": "Signed revenue excl. tax."
        },
        "revenue_change_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "average_ticket": {
          "type": [
            "number",
            "null"
          ]
        },
        "transformation_rate": {
          "$ref": "#/$defs/ReportRatio"
        },
        "cancellation_rate": {
          "$ref": "#/$defs/ReportRatio"
        },
        "cycle_average_days": {
          "type": [
            "number",
            "null"
          ]
        },
        "coverage": {
          "$ref": "#/$defs/ReportRatio"
        }
      }
    }
  }
}