{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ComfyUI curated model catalog",
  "description": "Validates services/comfyui/models.yaml — the curated SoT for ComfyUI models. The wizard ALSO live-scrapes HuggingFace and civitai; user additions go in services/comfyui/custom-models.yaml.",
  "type": "object",
  "required": ["models"],
  "additionalProperties": false,
  "properties": {
    "models": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/model_entry"
      }
    }
  },
  "definitions": {
    "model_entry": {
      "type": "object",
      "required": ["name", "category"],
      "anyOf": [
        {"required": ["url"]},
        {"required": ["files"]}
      ],
      "allOf": [
        {
          "if": {"not": {"required": ["files"]}},
          "then": {"required": ["url", "sha256"]}
        }
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Stable unique identifier used as the catalog key."
        },
        "category": {
          "type": "string",
          "enum": [
            "checkpoint",
            "vae",
            "lora",
            "controlnet",
            "ipadapter",
            "instantid",
            "upscaler",
            "embedding",
            "clip",
            "animatediff",
            "motion_lora",
            "video_model",
            "voice_model",
            "audio_model",
            "mesh_model",
            "diffusion_models",
            "text_encoders"
          ],
          "description": "Category drives the in-container target directory (CATEGORY_TARGET_DIR) and wizard display group."
        },
        "url": {
          "type": "string",
          "pattern": "^https://huggingface\\.co/[^/]+/[^/]+/resolve/[0-9a-f]{40}/.+$",
          "description": "Curated artifact URL pinned to an immutable 40-hex Hugging Face revision."
        },
        "files": {
          "type": "array",
          "minItems": 1,
          "items": {"$ref": "#/definitions/model_file"},
          "description": "Optional bundle files. When present, one logical catalog entry expands to one download row per file."
        },
        "family": {
          "type": "string",
          "description": "Display family label (e.g. 'SDXL', 'AnimateDiff'). Defaults to name if absent."
        },
        "size_gb": {
          "type": "number",
          "minimum": 0,
          "description": "Approximate disk size in GB. Surfaced in wizard; used for disk-space warnings."
        },
        "size_bytes": {
          "type": ["integer", "null"],
          "minimum": 0,
          "description": "Exact artifact size in bytes when known from an immutable upstream revision."
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "Exact lowercase SHA-256 digest. Required for every direct curated artifact."
        },
        "target_dir": {
          "type": "string",
          "description": "Override in-container subdirectory under /models. Defaults to CATEGORY_TARGET_DIR[category] when absent."
        },
        "min_vram_gb": {
          "type": ["number", "null"],
          "minimum": 0,
          "description": "Minimum GPU VRAM in GB. Adds a badge when the host has less."
        },
        "min_ram_gb": {
          "type": ["number", "null"],
          "minimum": 0,
          "description": "Recommended host or unified memory in GB, surfaced as a wizard badge."
        },
        "cpu_supported": {
          "type": "boolean",
          "description": "If false, adds a 'requires GPU' badge. Defaults to true."
        },
        "requires_custom_node": {
          "type": "array",
          "items": {"type": "string"},
          "description": "ComfyUI custom-node repo names required to use this model. Names allowlisted in custom-nodes.yaml are installed for active models and gate ComfyUI readiness; unlisted names only warn."
        },
        "popularity": {
          "type": "integer",
          "minimum": 0,
          "description": "Approximate popularity score (0-100). Used for wizard sort order."
        },
        "cloud_only": {
          "type": "boolean",
          "description": "If true, the model is only available via cloud API, not for local download."
        },
        "notes": {
          "type": ["string", "null"],
          "description": "One-line subtitle shown in the wizard option row."
        },
        "filename": {
          "type": ["string", "null"],
          "description": "Explicit on-disk filename. Required for civitai URLs whose URL path carries no real filename."
        },
        "essential": {
          "type": "boolean",
          "description": "If true, this entry is activated by default when COMFYUI_USER_MODELS is empty (DB-free replacement for the former essential column in public.comfyui_models)."
        },
        "provisioning_required": {
          "type": "boolean",
          "default": true,
          "description": "Whether a selected artifact must provision successfully before ComfyUI can become ready. Defaults to true; optional is explicit."
        },
        "precision": {
          "type": ["string", "null"],
          "enum": ["bf16", "fp16", "fp8", null],
          "description": "Preferred numeric precision for this logical model."
        },
        "variant": {
          "type": ["string", "null"],
          "description": "Human-readable artifact variant, such as mps-safe or fp8."
        },
        "host_constraints": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Optional host constraints for the logical model, such as mps or cuda."
        },
        "license_name": {
          "type": ["string", "null"],
          "description": "Human-readable model-weight license name shown during selection."
        },
        "license_url": {
          "type": ["string", "null"],
          "pattern": "^https?://",
          "description": "Pinned authoritative license URL for the model weights."
        },
        "license_restrictions": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Material operator obligations shown as warn-only wizard badges."
        }
      }
    },
    "model_file": {
      "type": "object",
      "required": ["role", "category", "url", "sha256"],
      "additionalProperties": false,
      "properties": {
        "role": {
          "type": "string",
          "minLength": 1,
          "description": "Stable role within the bundle, e.g. diffusion, text_encoder, vae, checkpoint."
        },
        "category": {
          "type": "string",
          "enum": [
            "checkpoint",
            "vae",
            "lora",
            "controlnet",
            "ipadapter",
            "instantid",
            "upscaler",
            "embedding",
            "clip",
            "animatediff",
            "motion_lora",
            "video_model",
            "voice_model",
            "audio_model",
            "mesh_model",
            "diffusion_models",
            "text_encoders"
          ]
        },
        "url": {
          "type": "string",
          "pattern": "^https://huggingface\\.co/[^/]+/[^/]+/resolve/[0-9a-f]{40}/.+$"
        },
        "filename": {
          "type": ["string", "null"]
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "target_dir": {
          "type": ["string", "null"],
          "description": "Explicit in-container subdirectory under /models. Defaults from category when absent."
        },
        "size_gb": {
          "type": ["number", "null"],
          "minimum": 0
        },
        "size_bytes": {
          "type": ["integer", "null"],
          "minimum": 0
        },
        "precision": {
          "type": ["string", "null"],
          "enum": ["bf16", "fp16", "fp8", null]
        },
        "variant": {
          "type": ["string", "null"]
        },
        "provisioning_required": {
          "type": "boolean",
          "description": "Optional per-file override of the logical model's readiness policy."
        }
      }
    }
  }
}