{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-analytics-breakdown-schema.json",
  "title": "AnalyticsBreakdown",
  "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/AnalyticsBreakdown",
  "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."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "timezone"
      ],
      "description": "Start and end of the period."
    },
    "by": {
      "type": "string",
      "enum": [
        "platform",
        "keyword",
        "sentiment",
        "intent",
        "status",
        "hour",
        "person",
        "language"
      ],
      "description": "Grouping used for the rows."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "What the row stands for. A platform name, keyword id, sentiment, intent or status, \"weekday-hour\" with by=hour, or a person key you should not parse."
          },
          "label": {
            "type": "string",
            "description": "A name to display. The keyword's term or the person's name, or else the key."
          },
          "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": "Set only with by=keyword. Null otherwise."
          },
          "person": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The person's aut_... id. Older posts, from before people were linked, have null."
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The name shown on the platform."
              },
              "platform": {
                "type": "string",
                "enum": [
                  "bluesky",
                  "hackernews",
                  "github",
                  "stackoverflow",
                  "devto",
                  "reddit",
                  "x",
                  "youtube",
                  "news",
                  "linkedin",
                  "tiktok",
                  "instagram",
                  "appstore",
                  "googleplay",
                  "trustpilot",
                  "googlemaps",
                  "rss"
                ],
                "description": "The platform. Review platforms are appstore, googleplay, trustpilot and googlemaps (a place's Google reviews)."
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Link to the profile."
              },
              "avatarUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Link to the profile picture, if the platform provided one."
              },
              "followers": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "description": "Follower count from the audience profile, or null."
              }
            },
            "required": [
              "id",
              "name",
              "platform",
              "url",
              "avatarUrl",
              "followers"
            ],
            "description": "Set only with by=person. Null otherwise."
          },
          "slot": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "weekday": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6,
                "description": "The day of the week, from 0 for Sunday to 6 for Saturday."
              },
              "hour": {
                "type": "integer",
                "minimum": 0,
                "maximum": 23,
                "description": "The hour, from 0 to 23."
              }
            },
            "required": [
              "weekday",
              "hour"
            ],
            "description": "Weekday and hour in `timezone` when by=hour, otherwise null."
          },
          "matched": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches in this row."
          },
          "relevant": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of them scored 40 or more."
          },
          "share": {
            "type": "number",
            "description": "The percentage of the window's matches that fall in this row, with one decimal. A mention can have several intents, so intent shares can total more than 100."
          },
          "sentiment": {
            "type": "object",
            "properties": {
              "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": [
              "positive",
              "neutral",
              "negative",
              "unclassified"
            ],
            "description": "Sentiment split of the matched mentions."
          },
          "previous": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "matched": {
                "type": "integer",
                "minimum": 0,
                "description": "Matches in this row during that period."
              },
              "relevant": {
                "type": "integer",
                "minimum": 0,
                "description": "Relevant matches in this row during that period."
              }
            },
            "required": [
              "matched",
              "relevant"
            ],
            "description": "This row for the period just before the window. Null unless compare=true."
          }
        },
        "required": [
          "key",
          "label",
          "keyword",
          "person",
          "slot",
          "matched",
          "relevant",
          "share",
          "sentiment",
          "previous"
        ]
      },
      "description": "Up to 50 rows, the one with the most matches first. With by=hour the rows are in time order and not limited, so up to 168."
    }
  },
  "required": [
    "window",
    "by",
    "data"
  ],
  "$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."
    }
  }
}