Metrics

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postlake-dev/json-schema/postlake-dev-metrics-schema.json",
  "title": "Metrics",
  "description": "Numeric counters retain compatibility. Optional reported lists fields actually returned by this observation, including measured zero. Missing reported means legacy availability is unknown. Do not interpret an omitted field as measured zero.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postlake-dev-openapi.json#/components/schemas/Metrics",
  "type": "object",
  "properties": {
    "reported": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "views",
          "impressions",
          "reach",
          "likes",
          "comments",
          "shares",
          "saves",
          "clicks"
        ]
      },
      "description": "Counters actually returned in this reading. An empty array means none. Omitted for legacy evidence with unknown field coverage."
    },
    "impressions": {
      "type": "integer",
      "description": "Times the content was DISPLAYED."
    },
    "views": {
      "type": "integer",
      "description": "Times it was actually WATCHED or opened. A subset of impressions, not a synonym, and networks that report only one of the two leave the other at 0 rather than filing a watch as a display."
    },
    "reach": {
      "type": "integer"
    },
    "likes": {
      "type": "integer"
    },
    "comments": {
      "type": "integer"
    },
    "shares": {
      "type": "integer"
    },
    "saves": {
      "type": "integer"
    },
    "clicks": {
      "type": "integer"
    },
    "followers": {
      "type": "integer"
    },
    "extras": {
      "type": "object",
      "additionalProperties": {
        "type": "number"
      },
      "description": "Metrics this network reports that have no cross-platform equivalent, keyed by the network's OWN metric name. Pinterest returns a video retention curve (VIDEO_START, VIDEO_10S_VIEW, QUARTILE_95_PERCENT_VIEW) plus PROFILE_VISIT and USER_FOLLOW; Facebook returns its own video and Page numbers. Keys are native and are never normalised, so it is always clear which network a figure came from and what it means there. Rates and averages are deliberately excluded: they cannot be summed across posts, and every one of them is derivable from the counts. Absent when the network reports nothing extra."
    }
  },
  "required": [
    "impressions",
    "reach",
    "likes",
    "comments",
    "shares",
    "saves",
    "clicks",
    "followers"
  ]
}