{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-analytics-series-schema.json",
  "title": "AnalyticsSeries",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/rumoro-dev-analytics-api-openapi.yml#/components/schemas/AnalyticsSeries",
  "type": "object",
  "properties": {
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "The first day included."
        },
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "The last day included."
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "description": "How many days the window spans."
        },
        "timezone": {
          "type": "string",
          "description": "The IANA time zone used to split the days."
        },
        "bucket": {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "week",
            "month"
          ],
          "description": "The size of each point. One of hour, day, week (Monday to Sunday) or month."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "timezone",
        "bucket"
      ],
      "description": "Start and end of the period."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "A platform name, a keyword id or a sentiment (positive, neutral, negative, unclassified). It is \"total\" when the series is not split and \"other\" for everything past the top 20."
          },
          "label": {
            "type": "string",
            "description": "Display name such as a platform, keyword term or sentiment, or \"Total\" and \"Other\"."
          },
          "keyword": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The keyword's id (kw_...)."
              },
              "term": {
                "type": "string",
                "description": "The term being tracked."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "brand",
                  "competitor",
                  "topic"
                ],
                "description": "The keyword's kind, brand, competitor or topic."
              },
              "group": {
                "allOf": [
                  {
                    "$ref": "#/$defs/GroupRef"
                  },
                  {
                    "description": "The keyword's group."
                  }
                ]
              }
            },
            "required": [
              "id",
              "term",
              "kind",
              "group"
            ],
            "description": "The keyword, when split by keyword. Otherwise null."
          },
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Start of the point in `timezone`. YYYY-MM-DD for a day, the Monday for a week, the 1st for a month, or YYYY-MM-DDTHH:00 for an hour."
                },
                "matched": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "All matches published during this point."
                },
                "relevant": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "How many of them scored 40 or more."
                },
                "positive": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with positive sentiment."
                },
                "neutral": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with neutral sentiment."
                },
                "negative": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with negative sentiment."
                },
                "unclassified": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches without a score, either still waiting or failed."
                }
              },
              "required": [
                "date",
                "matched",
                "relevant",
                "positive",
                "neutral",
                "negative",
                "unclassified"
              ]
            },
            "description": "A point for every step of the window, oldest first, with zeros where nothing matched."
          }
        },
        "required": [
          "key",
          "label",
          "keyword",
          "points"
        ]
      },
      "description": "One item for each series, the one with the most matches first. Without a split there is a single \"total\" item."
    },
    "previous": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "A platform name, a keyword id or a sentiment (positive, neutral, negative, unclassified). It is \"total\" when the series is not split and \"other\" for everything past the top 20."
          },
          "label": {
            "type": "string",
            "description": "Display name such as a platform, keyword term or sentiment, or \"Total\" and \"Other\"."
          },
          "keyword": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The keyword's id (kw_...)."
              },
              "term": {
                "type": "string",
                "description": "The term being tracked."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "brand",
                  "competitor",
                  "topic"
                ],
                "description": "The keyword's kind, brand, competitor or topic."
              },
              "group": {
                "allOf": [
                  {
                    "$ref": "#/$defs/GroupRef"
                  },
                  {
                    "description": "The keyword's group."
                  }
                ]
              }
            },
            "required": [
              "id",
              "term",
              "kind",
              "group"
            ],
            "description": "The keyword, when split by keyword. Otherwise null."
          },
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Start of the point in `timezone`. YYYY-MM-DD for a day, the Monday for a week, the 1st for a month, or YYYY-MM-DDTHH:00 for an hour."
                },
                "matched": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "All matches published during this point."
                },
                "relevant": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "How many of them scored 40 or more."
                },
                "positive": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with positive sentiment."
                },
                "neutral": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with neutral sentiment."
                },
                "negative": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches with negative sentiment."
                },
                "unclassified": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Matches without a score, either still waiting or failed."
                }
              },
              "required": [
                "date",
                "matched",
                "relevant",
                "positive",
                "neutral",
                "negative",
                "unclassified"
              ]
            },
            "description": "A point for every step of the window, oldest first, with zeros where nothing matched."
          }
        },
        "required": [
          "key",
          "label",
          "keyword",
          "points"
        ]
      },
      "description": "With compare=true, the same items for the prior period in the same order, index-aligned with `data`. The last point can be missing when weeks split differently. Otherwise null."
    }
  },
  "required": [
    "window",
    "data",
    "previous"
  ],
  "$defs": {
    "GroupRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The group's id (grp_...)."
        },
        "name": {
          "type": "string",
          "description": "Name of the group."
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ],
          "description": "An id from your own system, or null."
        },
        "isDefault": {
          "type": "boolean",
          "description": "True for the workspace's default group. New keywords go there when you don't name a group."
        }
      },
      "required": [
        "id",
        "name",
        "externalId",
        "isDefault"
      ],
      "description": "The keyword's group."
    }
  }
}