{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://skillcatalog.dev/schemas/stack.schema.json",
  "title": "SkillCatalog Stack",
  "description": "A stack file (.yaml) groups skills for installation. The file has YAML frontmatter (delimited by --- lines) followed by a YAML body with a skills array. The runtime does not reject unknown keys in this file, so this schema does not either; a typo in an optional field will be silently ignored rather than flagged here.",
  "type": "object",
  "required": [
    "description",
    "author",
    "created_at",
    "updated_at",
    "skills"
  ],
  "additionalProperties": true,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Human-readable stack name. If omitted in frontmatter, defaults to the slug."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "One-sentence summary of what this stack provides."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,127}$",
        "description": "Slug of a tag defined in catalog.yaml taxonomy. Must be a lowercase alphanumeric slug, max 128 characters; runtime validation rejects other shapes."
      },
      "default": [],
      "description": "Tags from the catalog.yaml taxonomy. Each tag must be a valid slug."
    },
    "owner": {
      "type": "string",
      "description": "Slug of an owner defined in catalog.yaml taxonomy. An empty value is treated as absent.",
      "anyOf": [
        {
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,127}$"
        },
        {
          "const": ""
        }
      ]
    },
    "author": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Author name. Required during validation."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp (UTC) when the stack was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp (UTC) of the last update. Must be >= created_at."
    },
    "status": {
      "type": "string",
      "description": "Obsolete field. Older catalogs may still carry it, so it is allowed here to keep those files schema-valid. The current runtime does not read it, does not act on it, and never writes it."
    },
    "skills": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,127}$",
        "description": "Slug of a skill in the same catalog."
      },
      "description": "Ordered list of skill slugs included in this stack. Must be non-empty and duplicate-free. The delivered skill set must stay closed over any @skill: references used by those skills."
    }
  }
}