{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://www.dsh.so/data/npm-downloads.schema.json",
  "title": "dsh.so npm weekly downloads ranking",
  "description": "npm weekly (last-week window) download ranking of DSH plugins, served at /data/npm-downloads.json. Same derivation as the homepage 'npm downloads this week' board (src/data/trending.ts getDownloadTrend): listable artifacts only, ecosystem apps excluded, entries indexed inside the 7-day window excluded. Provides the top 100 entries only.",
  "type": "object",
  "required": [
    "generatedAt",
    "snapshotDate",
    "window",
    "limit",
    "count",
    "items",
    "license"
  ],
  "additionalProperties": true,
  "properties": {
    "schema": {
      "type": "string",
      "description": "Absolute URL of this JSON Schema."
    },
    "generatedAt": {
      "type": "string",
      "description": "Build timestamp — preserve it alongside any cached copy."
    },
    "source": {
      "type": "string",
      "description": "Provenance note (npm Downloads API daily snapshots collected by the dsh.so pipelines)."
    },
    "snapshotDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Date (YYYY-MM-DD) of the npm snapshot the week values come from; null when no snapshot exists."
    },
    "window": {
      "type": "object",
      "required": [
        "days"
      ],
      "additionalProperties": true,
      "properties": {
        "days": {
          "const": 7,
          "description": "npm official last-week rolling 7-day window."
        },
        "start": {
          "type": [
            "string",
            "null"
          ],
          "description": "Window start = snapshotDate - 7 days; null when snapshotDate is null."
        },
        "end": {
          "type": [
            "string",
            "null"
          ],
          "description": "Window end = snapshotDate."
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "listableOnly": {
          "const": true
        },
        "ecosystemAppsExcluded": {
          "const": true
        },
        "newlyIndexedExcludedDays": {
          "const": 7
        }
      }
    },
    "count": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of ranked entries (= items.length); capped by limit."
    },
    "limit": {
      "const": 100,
      "description": "The feed provides the top 100 entries only (2026-09-20)."
    },
    "items": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "required": [
          "rank",
          "id",
          "name",
          "packageName",
          "week",
          "total",
          "stars",
          "url"
        ],
        "additionalProperties": true,
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1,
            "description": "1-based position, sorted by week descending."
          },
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
            "description": "Plugin id (matches plugins.json ids and artifact slugs)."
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "packageName": {
            "type": "string",
            "description": "npm package name the downloads are counted on."
          },
          "week": {
            "type": "integer",
            "minimum": 1,
            "description": "Downloads over the npm last-week rolling 7-day window. Rolling windows overlap across snapshot dates — never sum week values across snapshots; use daily snapshots for accumulation."
          },
          "total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Cumulative downloads (baseline + daily accumulation, maintained by scripts/npm-cumulative.ts); null when no baseline was ever collected — never reported as 0."
          },
          "stars": {
            "type": "integer",
            "minimum": 0,
            "description": "GitHub star count."
          },
          "url": {
            "type": "string",
            "description": "Absolute plugin detail page URL on dsh.so."
          }
        }
      }
    },
    "license": {
      "type": "object",
      "required": [
        "data",
        "reuse",
        "attribution",
        "spdx",
        "terms"
      ],
      "additionalProperties": true,
      "properties": {
        "data": {
          "type": "string"
        },
        "reuse": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "spdx": {
          "const": "CC-BY-4.0"
        },
        "terms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}