RepositoryKnowledge

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ayhire-com/json-schema/ayhire-com-repository-knowledge-schema.json",
  "title": "RepositoryKnowledge",
  "description": "What DeepWiki's generated wiki says about a public repo. Secondary evidence: never proof of who wrote anything.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ayhire-com-openapi.yml#/components/schemas/RepositoryKnowledge",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "description": "owner/name as GitHub spells it"
    },
    "state": {
      "type": "string",
      "description": "How it went. ok: an answer with cited files; no_citations: an answer that cites nothing; pending: still answering (ask again)",
      "enum": [
        "ok",
        "no_citations",
        "not_indexed",
        "unavailable",
        "timeout",
        "invalid_response",
        "pending"
      ]
    },
    "source_tier": {
      "type": "string",
      "description": "Generated by the provider's model from the repo's files",
      "enum": [
        "provider_generated"
      ]
    },
    "secondary_evidence": {
      "type": "boolean",
      "description": "Always true: check claims against the cited files"
    },
    "provider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "server": {
          "type": "string"
        },
        "server_version": {
          "type": [
            "string",
            "null"
          ]
        },
        "tool": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "server"
      ]
    },
    "fetched_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When DeepWiki was read"
    },
    "cached": {
      "type": "boolean",
      "description": "Served from AyHire's short-lived cache"
    },
    "expires_at": {
      "type": "string",
      "description": "When a saved answer is asked again",
      "format": "date-time"
    },
    "request_id": {
      "type": "string",
      "description": "The saved question (ask only)",
      "format": "uuid"
    },
    "retry_after_sec": {
      "type": "integer",
      "description": "With pending: ask again after this many seconds"
    },
    "revision": {
      "type": "object",
      "properties": {
        "indexed_commit": {
          "type": "null"
        },
        "known": {
          "type": "boolean",
          "description": "Always false: DeepWiki doesn't say which commit it read"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "indexed_commit",
        "known",
        "note"
      ]
    },
    "github": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "stars": {
          "type": "integer"
        },
        "language": {
          "type": [
            "string",
            "null"
          ]
        },
        "license": {
          "type": [
            "string",
            "null"
          ],
          "description": "SPDX id"
        },
        "default_branch": {
          "type": "string"
        },
        "pushed_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "head_commit_now": {
          "type": [
            "string",
            "null"
          ],
          "description": "The default branch's newest commit today, from GitHub; not what DeepWiki read"
        }
      },
      "required": [
        "url",
        "default_branch"
      ]
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "e.g. 4.1"
          },
          "title": {
            "type": "string"
          },
          "depth": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "title",
          "depth"
        ]
      }
    },
    "page": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "text": {
              "type": "string",
              "description": "Cleaned generated text, at most 12,000 characters"
            },
            "truncated": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "title",
            "text"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "answer": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "question": {
              "type": "string"
            },
            "text": {
              "type": "string",
              "description": "Cleaned generated text, at most 8,000 characters"
            },
            "truncated": {
              "type": "boolean"
            }
          },
          "required": [
            "question",
            "text"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "lines": {
            "type": [
              "string",
              "null"
            ],
            "description": "8-12, 8, or null for the whole file"
          },
          "url": {
            "type": "string",
            "description": "A github.com link on the default branch now"
          },
          "link_revision": {
            "type": "string",
            "enum": [
              "default branch now"
            ]
          },
          "check": {
            "type": "string",
            "description": "Whether the path is on the default branch now",
            "enum": [
              "exists_now",
              "not_found_now",
              "unchecked"
            ]
          },
          "inferred": {
            "type": "boolean",
            "description": "DeepWiki marked it inferred from documentation"
          }
        },
        "required": [
          "path",
          "url",
          "check"
        ]
      }
    },
    "coverage": {
      "type": "object",
      "properties": {
        "topics": {
          "type": [
            "integer",
            "null"
          ]
        },
        "cited_paths": {
          "type": "integer"
        },
        "exists_now": {
          "type": "integer"
        },
        "not_found_now": {
          "type": "integer"
        },
        "unchecked": {
          "type": "integer"
        }
      }
    },
    "possibly_stale": {
      "type": "boolean",
      "description": "At least half of the checked files aren't on the default branch now"
    },
    "rejected_claims": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "description": "Sentences removed because they said who wrote the code"
    },
    "untrusted_text_note": {
      "type": "string"
    },
    "deepwiki_url": {
      "type": "string",
      "description": "For information; AyHire never asks DeepWiki to index a repo"
    },
    "fallback": {
      "type": "object",
      "properties": {
        "source_tier": {
          "type": "string",
          "enum": [
            "github_readme"
          ]
        },
        "readme_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "readme_excerpt": {
          "type": [
            "string",
            "null"
          ],
          "description": "The README's first 2,000 characters"
        },
        "github": {
          "type": "object"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "source_tier",
        "github"
      ],
      "description": "When state isn't ok or pending: the README and GitHub's facts, read live"
    },
    "note": {
      "type": "string",
      "description": "What the state means, in a sentence or two"
    }
  },
  "required": [
    "repo",
    "state",
    "source_tier",
    "secondary_evidence",
    "provider",
    "revision",
    "github",
    "citations",
    "coverage",
    "possibly_stale",
    "rejected_claims",
    "note"
  ]
}