{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://www.dsh.so/data/npm-popular.schema.json",
  "title": "dsh.so npm downloads popularity ranking (all-time)",
  "description": "All-time npm downloads popularity ranking of DSH plugins, served at /data/npm-popular.json — ranked by cumulative downloads (baseline + daily accumulation), the sibling feed of /data/npm-downloads.json which ranks the weekly window. Listable artifacts only, ecosystem apps excluded. Coverage is honest by absence: only packages whose initial total baseline was ever collected appear; never-baselined packages are missing (never reported as 0). Provides the top 100 entries only.",
  "type": "object",
  "required": [
    "generatedAt",
    "totalsAsOf",
    "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 + cumulative accumulation by the dsh.so pipelines)."
    },
    "totalsAsOf": {
      "type": [
        "string",
        "null"
      ],
      "description": "Latest cumulative-total as-of date (YYYY-MM-DD) across the ranked entries; null when the feed is empty."
    },
    "scope": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "listableOnly": {
          "const": true
        },
        "ecosystemAppsExcluded": {
          "const": true
        },
        "packagesWithBaselineOnly": {
          "const": true
        }
      }
    },
    "limit": {
      "const": 100,
      "description": "The feed provides the top 100 entries only (2026-09-20)."
    },
    "count": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of ranked entries (= items.length); capped by limit."
    },
    "items": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "required": [
          "rank",
          "id",
          "name",
          "packageName",
          "total",
          "totalAsOf",
          "week",
          "stars",
          "url"
        ],
        "additionalProperties": true,
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1,
            "description": "1-based position, sorted by total descending (1-100)."
          },
          "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."
          },
          "total": {
            "type": "integer",
            "minimum": 1,
            "description": "Cumulative downloads = initial baseline + daily accumulation; never fabricated from partial daily sums."
          },
          "totalAsOf": {
            "type": [
              "string",
              "null"
            ],
            "description": "As-of date of this cumulative total (baseline date, or the last day accumulated onto it)."
          },
          "week": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Weekly (npm last-week rolling window) downloads, as context next to the all-time total; null when no snapshot covers this package."
          },
          "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"
          }
        }
      }
    }
  }
}