{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mentio-dev/json-schema/mentio-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/mentio-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": "First day, inclusive."
        },
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Last day, inclusive."
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "description": "Length of the window in days."
        },
        "timezone": {
          "type": "string",
          "description": "IANA zone the days were cut in."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "timezone"
      ],
      "description": "The window the report covers."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Keyword id (kw_...)."
              },
              "term": {
                "type": "string",
                "description": "The tracked term."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "brand",
                  "competitor",
                  "topic"
                ],
                "description": "brand, competitor or topic."
              },
              "group": {
                "allOf": [
                  {
                    "$ref": "#/$defs/GroupRef"
                  },
                  {
                    "description": "The group the keyword is in."
                  }
                ]
              }
            },
            "required": [
              "id",
              "term",
              "kind",
              "group"
            ],
            "description": "The keyword this row is about."
          },
          "matched": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches of this keyword in the window."
          },
          "relevant": {
            "type": "integer",
            "minimum": 0,
            "description": "Of those, scored at or above the relevance threshold."
          },
          "negative": {
            "type": "integer",
            "minimum": 0,
            "description": "Of those, classified negative."
          },
          "buyIntent": {
            "type": "integer",
            "minimum": 0,
            "description": "Of those, carrying the buy_intent intent."
          },
          "share": {
            "type": [
              "number",
              "null"
            ],
            "description": "Percent of brand plus competitor matches, one decimal; null for topics, which stay out of the split."
          },
          "previous": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "matched": {
                "type": "integer",
                "minimum": 0,
                "description": "Matches of this keyword then."
              }
            },
            "required": [
              "matched"
            ],
            "description": "The same keyword over the period right before the window; null unless compare=true."
          }
        },
        "required": [
          "keyword",
          "matched",
          "relevant",
          "negative",
          "buyIntent",
          "share",
          "previous"
        ]
      },
      "description": "Every keyword matched in the window, most matched first."
    }
  },
  "required": [
    "window",
    "data"
  ],
  "$defs": {
    "GroupRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Group id (grp_...)."
        },
        "name": {
          "type": "string",
          "description": "The group's name."
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Your own id for the group, or null."
        },
        "isDefault": {
          "type": "boolean",
          "description": "The workspace's default group, where a keyword lands when no group is named."
        }
      },
      "required": [
        "id",
        "name",
        "externalId",
        "isDefault"
      ],
      "description": "The group the keyword belongs to."
    }
  }
}