{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-share-of-voice-schema.json",
  "title": "ShareOfVoice",
  "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/ShareOfVoice",
  "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."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "object",
            "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": "Which keyword the row covers."
          },
          "matched": {
            "type": "integer",
            "minimum": 0,
            "description": "This keyword's match count in the window."
          },
          "relevant": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of them scored 40 or more."
          },
          "negative": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of them were negative."
          },
          "buyIntent": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of them were tagged buy_intent."
          },
          "share": {
            "type": [
              "number",
              "null"
            ],
            "description": "The percentage of all brand and competitor matches, with one decimal. Null for topics, which are not part of the split."
          },
          "previous": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "matched": {
                "type": "integer",
                "minimum": 0,
                "description": "The keyword's matches during that period."
              }
            },
            "required": [
              "matched"
            ],
            "description": "With compare=true, this keyword for the prior period. Otherwise null."
          }
        },
        "required": [
          "keyword",
          "matched",
          "relevant",
          "negative",
          "buyIntent",
          "share",
          "previous"
        ]
      },
      "description": "All keywords with matches in the window, the one with the most first."
    }
  },
  "required": [
    "window",
    "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."
    }
  }
}