ReportsOverview

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/joinways-app/json-schema/joinways-app-reports-overview-schema.json",
  "title": "ReportsOverview",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/joinways-app-openapi.yml#/components/schemas/ReportsOverview",
  "type": "object",
  "properties": {
    "today": {
      "type": "string",
      "format": "date"
    },
    "timezone": {
      "type": "string"
    },
    "venue_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "currency": {
      "type": "string"
    },
    "month": {
      "type": "object",
      "properties": {
        "month": {
          "type": "string"
        },
        "from": {
          "type": "string",
          "format": "date"
        },
        "to": {
          "type": "string",
          "format": "date"
        },
        "days_elapsed": {
          "type": "integer"
        },
        "days_in_month": {
          "type": "integer"
        }
      }
    },
    "month_to_date": {
      "type": "object",
      "properties": {
        "signed_revenue": {
          "$ref": "#/$defs/ReportMetric"
        },
        "previous_from": {
          "type": "string",
          "format": "date"
        },
        "previous_to": {
          "type": "string",
          "format": "date"
        },
        "signed": {
          "type": "integer"
        },
        "coverage": {
          "$ref": "#/$defs/ReportRatio"
        }
      }
    },
    "month_revenue": {
      "type": "object",
      "description": "Revenue of confirmed events dated in the current month (event date, as in accounting), which the goal measures.",
      "properties": {
        "revenue": {
          "$ref": "#/$defs/ReportMetric"
        },
        "realized_to_date": {
          "type": "number",
          "description": "Events already past, up to today."
        },
        "events": {
          "type": "integer"
        },
        "coverage": {
          "$ref": "#/$defs/ReportRatio"
        },
        "forecast": {
          "type": [
            "object",
            "null"
          ],
          "description": "Secured revenue plus the month's options weighted by their signing probability, with an 80 % range.",
          "properties": {
            "expected": {
              "type": "number"
            },
            "low": {
              "type": "number"
            },
            "high": {
              "type": "number"
            },
            "from_options": {
              "type": "number",
              "description": "Open options dated in the period × probability to sign before the event date (survival model on each option's history). An option without amount counts at its estimated amount (similar confirmed events)."
            },
            "from_unpriced_confirmed": {
              "type": "number",
              "description": "Confirmed events still without amount, at their estimated amount × share of past confirmed events that received one."
            },
            "from_upcoming_inquiries": {
              "type": "number",
              "description": "Revenue expected from inquiries not received yet (booking pace of past months)."
            }
          }
        },
        "like_for_like": {
          "type": [
            "object",
            "null"
          ],
          "description": "Month revenue without the venues opened or closed since last year (null when every venue was open both years). A venue is opened since last year when it had no confirmed event in the 12 months up to the same month last year, closed when it had none in the last 12 months.",
          "properties": {
            "revenue": {
              "$ref": "#/$defs/ReportMetric"
            },
            "opened_venues": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "location_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "revenue": {
                    "type": "number"
                  }
                }
              }
            },
            "closed_venues": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "location_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "previous_revenue": {
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      }
    },
    "goal": {
      "type": [
        "object",
        "null"
      ],
      "description": "Monthly realized-revenue goal, measured on month_revenue. All venues shown: the workspace goal, else the sum of the venue goals. Venue filter: the sum of the shown venues' goals. A sum is only given when every venue shown has a goal (see goal_missing_venues).",
      "properties": {
        "metric": {
          "type": "string",
          "enum": [
            "realized_revenue"
          ]
        },
        "amount": {
          "type": "number"
        },
        "secured_pct": {
          "type": "number",
          "description": "Confirmed events of the month / goal."
        },
        "realized_pct": {
          "type": "number",
          "description": "Events already past / goal."
        },
        "expected_pct": {
          "type": [
            "number",
            "null"
          ],
          "description": "Forecast (secured + weighted options) / goal."
        },
        "probability": {
          "type": [
            "number",
            "null"
          ],
          "description": "Probability (0–1) of reaching the goal."
        },
        "remaining": {
          "type": "number",
          "description": "Goal minus secured, ≥ 0."
        }
      }
    },
    "goal_missing_venues": {
      "type": "integer",
      "description": "Venues shown without a goal this month while others have one. goal is then null (incomplete goal)."
    },
    "booked_ahead": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "format": "date"
        },
        "to": {
          "type": "string",
          "format": "date"
        },
        "revenue": {
          "type": "number"
        },
        "events": {
          "type": "integer"
        }
      }
    },
    "pipeline": {
      "type": "object",
      "properties": {
        "open_options": {
          "type": "integer"
        },
        "valued_options": {
          "type": "integer"
        },
        "value": {
          "type": "number"
        },
        "weighted_value": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "win_rate_12_months": {
      "$ref": "#/$defs/ReportRate"
    },
    "first_response": {
      "type": "object",
      "properties": {
        "median_business_minutes": {
          "type": [
            "number",
            "null"
          ]
        },
        "previous_median_business_minutes": {
          "type": [
            "number",
            "null"
          ]
        },
        "answered": {
          "type": "integer"
        }
      }
    },
    "insights": {
      "type": "array",
      "description": "Up to 3 computed findings, each with `kind` (`venueDriver`, `sourceVolume`, `venueConversion`, `responseTime`), `tone` (`up`/`down`), `weight` and kind-specific fields (`location_id`, `source_key`, `delta`, `share`, `recent`, `baseline`, `change`, `recent_pct`, `baseline_pct`, `closed`, `recent_minutes`, `baseline_minutes`).",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "actions": {
      "type": "object",
      "properties": {
        "expiring_quotes": {
          "type": "object",
          "description": "Options whose quote expires within 7 days.",
          "properties": {
            "count": {
              "type": "integer"
            },
            "value": {
              "type": "number"
            },
            "event_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        },
        "viewed_quotes": {
          "type": "object",
          "description": "Quotes opened at least twice, last viewed within 7 days.",
          "properties": {
            "count": {
              "type": "integer"
            },
            "value": {
              "type": "number"
            },
            "event_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        },
        "pending_inquiries": {
          "type": "object",
          "description": "Inquiries of the last 30 days still to process.",
          "properties": {
            "pending": {
              "type": "integer"
            },
            "over_24h": {
              "type": "integer"
            },
            "oldest_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        "confirmed_without_amount": {
          "type": "integer"
        }
      }
    },
    "trend": {
      "type": "array",
      "description": "11 past months, the current month and 3 months ahead (revenue by event month).",
      "items": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string"
          },
          "future": {
            "type": "boolean"
          },
          "booked": {
            "type": "number"
          },
          "previous": {
            "type": "number",
            "description": "Same month one year earlier."
          },
          "events": {
            "type": "integer"
          },
          "forecast": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "expected": {
                "type": "number"
              },
              "low": {
                "type": "number"
              },
              "high": {
                "type": "number"
              },
              "from_options": {
                "type": "number",
                "description": "Open options dated in the period × probability to sign before the event date (survival model on each option's history). An option without amount counts at its estimated amount (similar confirmed events)."
              },
              "from_unpriced_confirmed": {
                "type": "number",
                "description": "Confirmed events still without amount, at their estimated amount × share of past confirmed events that received one."
              },
              "from_upcoming_inquiries": {
                "type": "number",
                "description": "Revenue expected from inquiries not received yet (booking pace of past months)."
              }
            }
          },
          "goal": {
            "type": [
              "number",
              "null"
            ],
            "description": "Realized-revenue goal of the month for the venues shown (same rule as goal). Null when not set or incomplete."
          },
          "goal_probability": {
            "type": [
              "number",
              "null"
            ],
            "description": "Upcoming months with a goal: probability (0-1) of reaching it, read from the simulated month (same model as goal.probability). Null for past months or without goal."
          }
        }
      }
    },
    "annotations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "format": "date"
          },
          "label": {
            "type": "string"
          },
          "location_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      }
    },
    "by_venue": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "location_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "month_revenue": {
            "type": "number"
          },
          "previous_month_revenue": {
            "type": "number"
          },
          "change_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "goal": {
            "type": [
              "number",
              "null"
            ]
          },
          "goal_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "win_rate_12_months": {
            "$ref": "#/$defs/ReportRatio"
          }
        }
      }
    },
    "by_source": {
      "type": "array",
      "description": "Top 6 sources by inquiries received over 12 months.",
      "items": {
        "type": "object",
        "properties": {
          "source_key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "received_12_months": {
            "type": "integer"
          },
          "win_rate_12_months": {
            "$ref": "#/$defs/ReportRatio"
          },
          "signed_revenue_12_months": {
            "type": "number"
          }
        }
      }
    }
  },
  "$defs": {
    "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"
        }
      }
    }
  }
}