{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/knowledge/json-schema/knowledge-observation-schema.json",
  "title": "API Knowledge Observation",
  "description": "A timestamped observation about an API — a single retrieval event that contributes evidence to a knowledge record. Multiple observations over time produce a history that lets consumers detect change.",
  "type": "object",
  "required": ["recordId", "observed", "source"],
  "properties": {
    "recordId": {
      "type": "string",
      "description": "ID of the knowledge record this observation belongs to."
    },
    "observed": {
      "type": "string",
      "format": "date-time"
    },
    "source": {
      "type": "string",
      "format": "uri"
    },
    "fields": {
      "type": "object",
      "description": "Field-level snapshot of what was observed (e.g. baseURL, version, rateLimit) at observation time.",
      "additionalProperties": true
    },
    "delta": {
      "type": "object",
      "description": "Optional diff against the previous observation.",
      "additionalProperties": true
    },
    "evidence": {
      "type": "array",
      "items": { "$ref": "knowledge-evidence-schema.json" }
    }
  },
  "additionalProperties": false
}