ProjectResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/git-top/json-schema/git-top-project-response-schema.json",
  "title": "ProjectResponse",
  "description": "Full project lookup response. Agents should read summary first, then classification, quality_signal_confidence, verification, metadata, and related evidence before citing claims.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/git-top-project-api-openapi.yml#/components/schemas/ProjectResponse",
  "type": "object",
  "required": [
    "project_id",
    "repo",
    "summary",
    "knowledge",
    "metadata"
  ],
  "properties": {
    "project_id": {
      "type": "string"
    },
    "repo": {
      "type": "string"
    },
    "resolved_from": {
      "type": "object",
      "additionalProperties": true
    },
    "summary": {
      "$ref": "#/$defs/ProjectSummary"
    },
    "project": {
      "$ref": "#/$defs/ProjectCard"
    },
    "knowledge": {
      "type": "object",
      "additionalProperties": true
    },
    "related": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "repo": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    },
    "score": {
      "type": "number"
    },
    "git_top_score": {
      "type": "number"
    },
    "quality_score": {
      "type": "number"
    },
    "agent_score": {
      "type": "number"
    },
    "classification": {
      "type": "object",
      "additionalProperties": true
    },
    "quality_signal_confidence": {
      "$ref": "#/$defs/QualitySignalConfidence"
    },
    "verification": {
      "$ref": "#/$defs/VerificationPackage"
    },
    "evidence": {
      "$ref": "#/$defs/NormalizedEvidence"
    },
    "caveats": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "confidence_reason": {
      "type": "string"
    },
    "source_fields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "last_verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "metadata": {
      "$ref": "#/$defs/Metadata"
    }
  },
  "additionalProperties": true,
  "$defs": {
    "Metadata": {
      "type": "object",
      "description": "Common provenance envelope for agent-facing responses. Agents should require source=d1 for high-confidence production claims and disclose seed fallback.",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "d1",
            "seed"
          ]
        },
        "reason": {
          "type": "string"
        },
        "project_count": {
          "type": "integer"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        },
        "snapshot_id": {
          "type": "string",
          "description": "Stable identity for the corpus snapshot used by this response."
        },
        "latest_synced_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "schema_version": {
          "type": "string",
          "enum": [
            "git-top.knowledge.v1"
          ]
        },
        "loaded_project_limit": {
          "type": "integer",
          "description": "Maximum D1 knowledge or search-candidate rows loaded into the bounded ranking set when present."
        },
        "truncated": {
          "type": "boolean",
          "description": "Whether the D1-backed ranking or candidate set reached its limit and may omit additional matching rows."
        },
        "candidate_retrieval": {
          "type": "string",
          "enum": [
            "d1_first"
          ],
          "description": "Search-only marker indicating that deterministic filters and broad query matching ran in D1 before TypeScript ranking."
        },
        "candidate_count": {
          "type": "integer",
          "description": "Number of D1 search candidates passed to the authoritative TypeScript filter and ranking stage."
        },
        "candidate_limit": {
          "type": "integer",
          "description": "Maximum number of D1 search candidates passed to the ranking stage."
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Fallback, count, freshness, or trust caveats that agents should account for before citing results."
        }
      }
    },
    "NormalizedEvidence": {
      "type": "object",
      "description": "Normalized evidence package for agent citation and caveat handling.",
      "properties": {
        "classification": {
          "type": "object",
          "additionalProperties": true
        },
        "quality_signal_confidence": {
          "$ref": "#/$defs/QualitySignalConfidence"
        },
        "verification": {
          "oneOf": [
            {
              "$ref": "#/$defs/VerificationPackage"
            },
            {
              "type": "null"
            }
          ]
        },
        "source_fields": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "confidence_reason": {
          "type": "string"
        },
        "last_verified_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    },
    "ProjectCard": {
      "type": "object",
      "description": "Compact project card used in search, recommendations, comparison, alternatives, and related project lists.",
      "required": [
        "project_id",
        "repo",
        "name"
      ],
      "properties": {
        "project_id": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "github_url": {
          "type": "string"
        },
        "homepage_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "type": [
            "string",
            "null"
          ]
        },
        "license": {
          "type": [
            "string",
            "null"
          ]
        },
        "project_kind": {
          "type": "string",
          "enum": [
            "project",
            "collection"
          ]
        },
        "collection_metadata": {
          "type": "object",
          "additionalProperties": true
        },
        "category": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "description": {
          "type": "string"
        },
        "overview": {
          "type": "string"
        },
        "deployments": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "difficulty": {
          "type": "string"
        },
        "cloudflare_ready": {
          "type": "boolean"
        },
        "git_top_score": {
          "type": "number"
        },
        "quality_score": {
          "type": "number"
        },
        "agent_score": {
          "type": "number"
        },
        "score": {
          "type": "number"
        },
        "classification": {
          "type": "object",
          "additionalProperties": true
        },
        "quality_signal_confidence": {
          "$ref": "#/$defs/QualitySignalConfidence"
        },
        "verification": {
          "$ref": "#/$defs/VerificationPackage"
        },
        "summary": {
          "$ref": "#/$defs/ProjectSummary"
        },
        "evidence": {
          "$ref": "#/$defs/NormalizedEvidence"
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "confidence_reason": {
          "type": "string"
        },
        "source_fields": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "last_verified_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    },
    "ProjectSummary": {
      "type": "object",
      "required": [
        "tl_dr",
        "purpose",
        "inputs",
        "outputs",
        "good_for",
        "not_good_for",
        "deployment",
        "alternatives"
      ],
      "properties": {
        "tl_dr": {
          "type": "string",
          "description": "One-sentence project overview for agents."
        },
        "purpose": {
          "type": "string",
          "description": "Longer agent-facing project purpose."
        },
        "install": {
          "type": [
            "string",
            "null"
          ],
          "description": "Conservative install or setup hint when Git.Top can infer one."
        },
        "inputs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "outputs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "good_for": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "not_good_for": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "deployment": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "alternatives": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "repo",
              "reason"
            ],
            "properties": {
              "repo": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "QualitySignalConfidence": {
      "type": "object",
      "description": "Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.",
      "properties": {
        "stars_30d_delta": {
          "type": "string",
          "enum": [
            "snapshot",
            "estimated"
          ]
        },
        "stars_30d_window_days": {
          "type": "integer"
        },
        "commits_30d": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "unknown"
          ]
        },
        "releases_180d": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "unknown"
          ]
        },
        "contributors_90d": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "unknown"
          ]
        }
      },
      "additionalProperties": true
    },
    "VerificationPackage": {
      "type": "object",
      "description": "Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.",
      "required": [
        "schema_version",
        "overall_status",
        "observed_at",
        "signals",
        "coverage",
        "next_steps"
      ],
      "properties": {
        "schema_version": {
          "type": "string",
          "const": "git-top.verification.v1"
        },
        "overall_status": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "unverified"
          ]
        },
        "observed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "signals": {
          "type": "object",
          "required": [
            "activity",
            "license",
            "documentation",
            "runtime",
            "install",
            "security",
            "mcp"
          ],
          "properties": {
            "activity": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "license": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "documentation": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "runtime": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "install": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "security": {
              "$ref": "#/$defs/VerificationSignal"
            },
            "mcp": {
              "$ref": "#/$defs/VerificationSignal"
            }
          },
          "additionalProperties": false
        },
        "coverage": {
          "type": "object",
          "required": [
            "observed",
            "inferred",
            "not_run",
            "unknown"
          ],
          "properties": {
            "observed": {
              "type": "integer",
              "minimum": 0
            },
            "inferred": {
              "type": "integer",
              "minimum": 0
            },
            "not_run": {
              "type": "integer",
              "minimum": 0
            },
            "unknown": {
              "type": "integer",
              "minimum": 0
            }
          },
          "additionalProperties": false
        },
        "next_steps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "VerificationSignal": {
      "type": "object",
      "description": "One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.",
      "required": [
        "status",
        "source",
        "evidence"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "verified",
            "observed",
            "inferred",
            "not_run",
            "not_applicable",
            "unknown"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "github_metadata",
            "git_top_heuristic",
            "git_top_runtime"
          ]
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    }
  }
}