{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentspot.dev/data/schema.json",
  "title": "AgentSpot directory data",
  "description": "Shape of every JSON payload published by AgentSpot. Facts here are compiled from public APIs and offered under CC-BY-4.0.",
  "$defs": {
    "listing": {
      "type": "object",
      "title": "Listing",
      "required": [
        "id",
        "name",
        "category",
        "description",
        "url",
        "repo_url",
        "website_url",
        "license",
        "package",
        "install",
        "can_run_locally",
        "is_mcp_server",
        "open_source",
        "first_party",
        "derivative_of",
        "github_stars",
        "downloads",
        "popularity_score",
        "unranked",
        "growth",
        "tags",
        "first_listed",
        "last_verified",
        "editorial_note",
        "sponsored",
        "tier",
        "curation"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier, `<category>/<slug>`. Never reused."
        },
        "name": {
          "type": "string",
          "description": "The project's own name."
        },
        "category": {
          "type": "string",
          "enum": [
            "agent",
            "skill",
            "tool",
            "coding",
            "education"
          ],
          "description": "One of: agent, skill, tool, coding, education."
        },
        "description": {
          "type": "string",
          "description": "A one- or two-sentence summary written by us — never copied from the README."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical AgentSpot page for this listing."
        },
        "repo_url": {
          "type": "string",
          "format": "uri",
          "description": "Source repository. Read this before running anything."
        },
        "website_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "The project's own site or docs, when it has one."
        },
        "license": {
          "type": "string",
          "description": "SPDX identifier where GitHub could classify it, otherwise \"Other (see repo)\"."
        },
        "package": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "registry": {
              "type": "string",
              "enum": [
                "npm",
                "pypi",
                "docker"
              ]
            },
            "name": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "description": "Registry coordinates for the published package, when one exists. `null` means the project is installed from source."
        },
        "install": {
          "type": [
            "string",
            "null"
          ],
          "description": "One-line install command derived from `package`. A starting point, not a substitute for the project's own instructions — check the repo for required flags, runtimes, and configuration."
        },
        "can_run_locally": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether the project can run entirely on your own machine, with no required hosted service. `null` where the question does not apply (a book, a prompt pack) or has not been assessed."
        },
        "is_mcp_server": {
          "type": "boolean",
          "description": "Heuristic: the project describes itself with MCP (Model Context Protocol) topics. A shortlisting hint, not a verified capability — we do not currently publish per-listing MCP endpoint URLs or config snippets."
        },
        "open_source": {
          "type": "boolean",
          "description": "False for listings whose source is not publicly available."
        },
        "first_party": {
          "type": "boolean",
          "description": "True for tools published by the lab or vendor whose model they serve."
        },
        "derivative_of": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "repo_url": {
              "type": "string",
              "format": "uri"
            }
          },
          "description": "Set when this listing is a fork that has overtaken the project it came from; points back at the original."
        },
        "github_stars": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Stars at `last_verified`."
        },
        "downloads": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "npm",
                "pypi",
                "docker"
              ]
            },
            "count": {
              "type": "integer"
            }
          },
          "description": "Downloads over the trailing 7 days, from the registry named in `source`. Container pulls count restarts as well as installs, so they are discounted in the score."
        },
        "popularity_score": {
          "type": [
            "number",
            "null"
          ],
          "description": "Composite 0–100 score. `null` when the listing is `unranked`. The formula is published at /methodology/."
        },
        "unranked": {
          "type": "boolean",
          "description": "Listed and shown, but deliberately excluded from popularity ordering. `editorial_note` says why."
        },
        "growth": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "stars_delta": {
              "type": "integer"
            },
            "stars_pct": {
              "type": "number"
            },
            "downloads_pct": {
              "type": [
                "number",
                "null"
              ]
            },
            "window_days": {
              "type": "integer"
            },
            "as_of": {
              "type": "string",
              "format": "date"
            }
          },
          "description": "Change over the trailing week, held steady between weekly updates. `null` until a listing has enough history."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The project's own repository topics, lightly cleaned."
        },
        "first_listed": {
          "type": "string",
          "format": "date",
          "description": "The date this listing first appeared here."
        },
        "last_verified": {
          "type": "string",
          "format": "date",
          "description": "The date the metrics above were last refreshed from public APIs."
        },
        "editorial_note": {
          "type": [
            "string",
            "null"
          ],
          "description": "A public note from us, where a listing needs one."
        },
        "sponsored": {
          "type": "object",
          "properties": {
            "active": {
              "type": "boolean"
            },
            "label": {
              "type": "string"
            },
            "start_date": {
              "type": [
                "string",
                "null"
              ],
              "format": "date"
            },
            "end_date": {
              "type": [
                "string",
                "null"
              ],
              "format": "date"
            }
          },
          "description": "Sponsorship never affects inclusion, ordering, or `popularity_score`. `active` is false on every listing today."
        },
        "tier": {
          "type": "string",
          "description": "\"standard\" for every listing today; reserved for a future curated tier."
        },
        "curation": {
          "type": [
            "object",
            "null"
          ],
          "description": "Reserved for future independent evaluation results. `null` today."
        }
      }
    },
    "indexListing": {
      "type": "object",
      "title": "Listing (compact)",
      "required": [
        "id",
        "name",
        "category",
        "description",
        "url",
        "repo_url",
        "package",
        "install",
        "can_run_locally",
        "is_mcp_server",
        "github_stars",
        "popularity_score",
        "tags"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier, `<category>/<slug>`. Never reused."
        },
        "name": {
          "type": "string",
          "description": "The project's own name."
        },
        "category": {
          "type": "string",
          "enum": [
            "agent",
            "skill",
            "tool",
            "coding",
            "education"
          ],
          "description": "One of: agent, skill, tool, coding, education."
        },
        "description": {
          "type": "string",
          "description": "A one- or two-sentence summary written by us — never copied from the README."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical AgentSpot page for this listing."
        },
        "repo_url": {
          "type": "string",
          "format": "uri",
          "description": "Source repository. Read this before running anything."
        },
        "package": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "registry": {
              "type": "string",
              "enum": [
                "npm",
                "pypi",
                "docker"
              ]
            },
            "name": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "description": "Registry coordinates for the published package, when one exists. `null` means the project is installed from source."
        },
        "install": {
          "type": [
            "string",
            "null"
          ],
          "description": "One-line install command derived from `package`. A starting point, not a substitute for the project's own instructions — check the repo for required flags, runtimes, and configuration."
        },
        "can_run_locally": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether the project can run entirely on your own machine, with no required hosted service. `null` where the question does not apply (a book, a prompt pack) or has not been assessed."
        },
        "is_mcp_server": {
          "type": "boolean",
          "description": "Heuristic: the project describes itself with MCP (Model Context Protocol) topics. A shortlisting hint, not a verified capability — we do not currently publish per-listing MCP endpoint URLs or config snippets."
        },
        "github_stars": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Stars at `last_verified`."
        },
        "popularity_score": {
          "type": [
            "number",
            "null"
          ],
          "description": "Composite 0–100 score. `null` when the listing is `unranked`. The formula is published at /methodology/."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The project's own repository topics, lightly cleaned."
        }
      }
    }
  },
  "oneOf": [
    {
      "title": "Full payload (/data/all.json, /data/<category>.json, /data/listings/<id>.json)",
      "type": "object",
      "required": [
        "_license",
        "api_version",
        "generated",
        "count",
        "listings"
      ],
      "properties": {
        "_license": {
          "type": "string",
          "description": "SPDX identifier of the dataset license."
        },
        "_license_url": {
          "type": "string",
          "format": "uri"
        },
        "_attribution": {
          "type": "string",
          "description": "The attribution string to reproduce when reusing this data."
        },
        "api_version": {
          "type": "integer",
          "description": "Incremented only for breaking changes to the record shape."
        },
        "generated": {
          "type": "string",
          "format": "date-time",
          "description": "When this file was built."
        },
        "category": {
          "type": "string",
          "description": "\"all\", or the category slug this file covers."
        },
        "count": {
          "type": "integer"
        },
        "listings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/listing"
          }
        }
      }
    },
    {
      "title": "Compact index (/data/index.json)",
      "type": "object",
      "required": [
        "_license",
        "api_version",
        "generated",
        "count",
        "listings"
      ],
      "properties": {
        "_license": {
          "type": "string",
          "description": "SPDX identifier of the dataset license."
        },
        "_license_url": {
          "type": "string",
          "format": "uri"
        },
        "_attribution": {
          "type": "string",
          "description": "The attribution string to reproduce when reusing this data."
        },
        "api_version": {
          "type": "integer",
          "description": "Incremented only for breaking changes to the record shape."
        },
        "generated": {
          "type": "string",
          "format": "date-time",
          "description": "When this file was built."
        },
        "category": {
          "type": "string",
          "description": "\"all\", or the category slug this file covers."
        },
        "count": {
          "type": "integer"
        },
        "listings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/indexListing"
          }
        }
      }
    }
  ]
}