nix-config/docs/version.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.invalid/version.schema.json",
  "title": "Unified Package Version Schema",
  "description": "Schema for a unified version.json used by packages/",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "sources"
  ],
  "properties": {
    "schemaVersion": {
      "type": "integer",
      "enum": [1],
      "description": "Schema version. Start at 1; bump on breaking changes."
    },
    "variables": {
      "type": "object",
      "description": "Common variables available for template substitution in string fields.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "defaultVariant": {
      "type": "string",
      "description": "Optional default variant name for consumers."
    },
    "sources": {
      "type": "object",
      "description": "Base component sources keyed by component name.",
      "minProperties": 1,
      "additionalProperties": {
        "$ref": "#/$defs/SourceSpec"
      }
    },
    "variants": {
      "type": "object",
      "description": "Optional variants/channels/flavors; each overlays the base.",
      "additionalProperties": {
        "$ref": "#/$defs/VariantSpec"
      }
    },
    "notes": {
      "type": "object",
      "description": "Optional free-form human notes/documentation.",
      "additionalProperties": true
    }
  },
  "$defs": {
    "SourceSpecBase": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "fetcher": {
          "type": "string",
          "enum": ["github", "git", "url", "pypi", "none"],
          "description": "Fetcher type for this source."
        },
        "hash": {
          "type": "string",
          "pattern": "^sha[0-9]+-",
          "description": "SRI hash for the fetched artifact. Required unless fetcher is 'none'."
        },
        "version": {
          "type": "string",
          "description": "Optional version string metadata for this component."
        },
        "extra": {
          "type": "object",
          "description": "Optional free-form metadata for consumer logic.",
          "additionalProperties": true
        },

        "owner": { "type": "string", "description": "GitHub owner/org (github fetcher)." },
        "repo":  { "type": "string", "description": "GitHub repository (github fetcher)." },
        "tag":   { "type": "string", "description": "Git tag (github fetcher). Mutually exclusive with 'rev'." },
        "rev":   { "type": "string", "description": "Commit revision (github/git fetchers)." },
        "branch": { "type": "string", "description": "Branch to track for HEAD-commit updates (github/git fetchers). Stored alongside 'rev' to record which branch the pinned commit came from. Has no effect on the Nix fetcher itself — only used by the version management tooling." },
        "submodules": { "type": "boolean", "description": "Whether to fetch submodules (github/git fetchers)." },

        "url": { "type": "string", "description": "Final URL (url fetcher). May be templated." },
        "urlTemplate": { "type": "string", "description": "Template for URL (url fetcher); supports ${var}." },

        "name": { "type": "string", "description": "PyPI dist name (pypi fetcher)." }
      }
    },

    "SourceSpec": {
      "allOf": [
        { "$ref": "#/$defs/SourceSpecBase" },
        {
          "if": {
            "properties": { "fetcher": { "const": "github" } },
            "required": ["fetcher"]
          },
          "then": {
            "required": ["owner", "repo"],
            "oneOf": [
              { "required": ["tag"] },
              { "required": ["rev"] }
            ]
          }
        },
        {
          "if": {
            "properties": { "fetcher": { "const": "git" } },
            "required": ["fetcher"]
          },
          "then": {
            "required": ["url", "rev"]
          }
        },
        {
          "if": {
            "properties": { "fetcher": { "const": "url" } },
            "required": ["fetcher"]
          },
          "then": {
            "oneOf": [
              { "required": ["url"] },
              { "required": ["urlTemplate"] }
            ]
          }
        },
        {
          "if": {
            "properties": { "fetcher": { "const": "pypi" } },
            "required": ["fetcher"]
          },
          "then": {
            "required": ["name", "version"]
          }
        },
        {
          "if": {
            "properties": { "fetcher": { "enum": ["github", "git", "url", "pypi"] } },
            "required": ["fetcher"]
          },
          "then": {
            "required": ["hash"]
          }
        }
      ]
    },

    "SourceOverride": {
      "type": "object",
      "additionalProperties": false,
      "description": "Partial override of a source within a variant. All fields optional.",
      "properties": {
        "fetcher": { "type": "string", "enum": ["github", "git", "url", "pypi", "none"] },
        "hash":    { "type": "string", "pattern": "^sha[0-9]+-" },
        "version": { "type": "string" },
        "extra":   { "type": "object", "additionalProperties": true },

        "owner": { "type": "string" },
        "repo":  { "type": "string" },
        "tag":   { "type": "string" },
        "rev":   { "type": "string" },
        "branch": { "type": "string" },
        "submodules": { "type": "boolean" },

        "url":         { "type": "string" },
        "urlTemplate": { "type": "string" },

        "name": { "type": "string" }
      }
    },

    "VariantSpec": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "inherits": {
          "type": "string",
          "description": "Optional base variant to inherit from."
        },
        "variables": {
          "type": "object",
          "description": "Variant-level variables that overlay top-level variables.",
          "additionalProperties": { "type": "string" }
        },
        "sources": {
          "type": "object",
          "description": "Per-component overrides for this variant.",
          "additionalProperties": { "$ref": "#/$defs/SourceOverride" }
        },
        "platforms": {
          "type": "object",
          "description": "Optional per-system overrides to support differing hashes/fields by platform.",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "sources": {
                "type": "object",
                "additionalProperties": { "$ref": "#/$defs/SourceOverride" }
              },
              "variables": {
                "type": "object",
                "additionalProperties": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}