API Knowledge · Schema

API Knowledge Observation

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.

API KnowledgeKnowledge GraphsAPI DiscoveryAPI SearchCatalogsIndexesRegistriesRAGSemantic WebJSON-LDLLMsAI AgentsTopic

Properties

Name Type Description
recordId string ID of the knowledge record this observation belongs to.
observed string
source string
fields object Field-level snapshot of what was observed (e.g. baseURL, version, rateLimit) at observation time.
delta object Optional diff against the previous observation.
evidence array
View JSON Schema on GitHub

JSON Schema

knowledge-observation-schema.json Raw ↑
{
  "$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
}