github__gh-stack/internal/stack/schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "gh-stack file",
  "description": "Schema for the .git/gh-stack file that stores the state of all stacks in a repository.",
  "type": "object",
  "required": ["schemaVersion", "stacks"],
  "properties": {
    "schemaVersion": {
      "type": "integer",
      "const": 1,
      "description": "Schema version for forward compatibility."
    },
    "repository": {
      "type": "string",
      "description": "The host:owner/name of the repository (e.g. 'github.com:github/gh-stack')."
    },
    "stacks": {
      "type": "array",
      "description": "All stacks tracked in this repository.",
      "items": { "$ref": "#/$defs/stack" }
    }
  },
  "$defs": {
    "stack": {
      "type": "object",
      "description": "A single stack of branches.",
      "required": ["trunk", "branches"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier for this stack, populated from the API when available."
        },
        "prefix": {
          "type": "string",
          "description": "Branch name prefix for the stack (e.g. 'myfeature')."
        },
        "numbered": {
          "type": "boolean",
          "description": "Whether to use auto-incrementing numbered branch names."
        },
        "trunk": {
          "$ref": "#/$defs/branchRef",
          "description": "The trunk (base) branch of the stack."
        },
        "branches": {
          "type": "array",
          "description": "Ordered list of branches in the stack, from bottom to top.",
          "items": { "$ref": "#/$defs/branchRef" }
        }
      }
    },
    "branchRef": {
      "type": "object",
      "description": "A reference to a branch and its associated commit hash. For the trunk, 'head' stores the HEAD commit. For stacked branches, 'base' stores the parent branch's HEAD SHA at the time of last sync/rebase.",
      "required": ["branch"],
      "properties": {
        "branch": {
          "type": "string",
          "description": "The branch name."
        },
        "head": {
          "type": "string",
          "description": "The HEAD commit SHA of this branch. Used for the trunk branch."
        },
        "base": {
          "type": "string",
          "description": "The parent branch's HEAD SHA at the time of last sync/rebase. Used to identify which commits are unique to this branch."
        },
        "pullRequest": {
          "$ref": "#/$defs/pullRequestRef",
          "description": "Associated pull request information, if a PR exists for this branch."
        }
      }
    },
    "pullRequestRef": {
      "type": "object",
      "description": "A snapshot of pull request metadata.",
      "required": ["number"],
      "properties": {
        "number": {
          "type": "integer",
          "description": "The PR number, scoped to the repository."
        },
        "id": {
          "type": "string",
          "description": "The PR global node ID."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Direct URL to the pull request."
        },
        "merged": {
          "type": "boolean",
          "description": "Whether the pull request has been merged."
        }
      }
    }
  }
}