{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/confighub/json-schema/confighub-promote-request-schema.json",
  "title": "PromoteRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/confighub-promote-api-openapi.yml#/components/schemas/PromoteRequest",
  "type": "object",
  "properties": {
    "ChangeDescription": {
      "type": "string",
      "description": "Recorded on each Unit write.",
      "x-go-type-skip-optional-pointer": true
    },
    "ChangeOrderID": {
      "type": "string",
      "description": "The ChangeOrder to promote. Without one, everything each upstream has reached is promoted. With one, only its range is, into the Spaces it is headed for.",
      "format": "uuid"
    },
    "ChangeSetID": {
      "type": "string",
      "description": "An existing open ChangeSet to record every write in.",
      "format": "uuid"
    },
    "Clearance": {
      "allOf": [
        {
          "$ref": "#/$defs/Clearance"
        }
      ],
      "description": "The guarded reasons the writes are cleared for. A path whose guards this does not cover is not written, and the withheld change is reported in the Unit's Conflicts."
    },
    "DryRun": {
      "type": "boolean",
      "description": "Plan the promotion, evaluate its gates, and return the same response without writing anything.",
      "x-go-type-skip-optional-pointer": true
    },
    "ExpectedPlan": {
      "type": "string",
      "description": "The Plan a previous dry run returned. If the plan now differs, nothing is written and the request fails with 412.",
      "x-go-type-skip-optional-pointer": true
    },
    "Force": {
      "type": "boolean",
      "description": "Promote even though the Stage's entry gates do not hold. Requires ForceReason, and Edit permission on the ChangeOrder, where the override is recorded.",
      "x-go-type-skip-optional-pointer": true
    },
    "ForceReason": {
      "type": "string",
      "description": "Why the gates were overridden. Required with Force.",
      "x-go-type-skip-optional-pointer": true
    },
    "Guards": {
      "allOf": [
        {
          "$ref": "#/$defs/GuardStamp"
        }
      ],
      "description": "Reasons to record on the paths each Unit write changes. A later operation must be cleared for them before overwriting those paths. Clearance must cover them, since a write is withheld by guards it is not cleared for, its own included."
    },
    "PriorRevisions": {
      "enum": [
        "Include",
        "Skip",
        "Error",
        "All"
      ],
      "type": "string",
      "description": "With a ChangeOrder, what to do for a Unit whose last merged upstream Revision is before the ChangeOrder's start there -- typically because a Link in the upstream Space, such as a TransformPaths Link, wrote Revisions after the Unit last merged. Include merges those Revisions first, as Revisions of their own that do not carry the ChangeOrder, and then the ChangeOrder's range; Skip merges only the ChangeOrder's range, as though the Unit had already merged as far as its start, and those Revisions do not arrive later; Error refuses, naming the Revisions; All merges them as Include does, and also marks every Unit in the Space the change does not change at its head, so the next promotion brings it up to this Space. Defaults to the ChangeOrder's PriorRevisions, or Include. A Unit that has merged past the ChangeOrder's start is an error whatever this says. Refused with an Insert, Upsert, or TransformPaths ChangeOrder, whose Links read their sources as they are at its end rather than merging a range.",
      "x-go-type-skip-optional-pointer": true
    },
    "Protect": {
      "type": "boolean",
      "description": "Record the paths each Unit write changes as protected local overrides, so a later merge from upstream does not overwrite them. By default a write claims nothing and each path keeps the protection it already had. Accepted only for an Invoke ChangeOrder and for one that follows Insert, Upsert, or TransformPaths Links: refused for a promotion that merges, which protection holds paths against.",
      "x-go-type-skip-optional-pointer": true
    },
    "SpaceFilterID": {
      "type": "string",
      "description": "A Filter over Spaces selecting the Spaces to promote. Intersected with the other selectors.",
      "format": "uuid"
    },
    "Squash": {
      "type": "boolean",
      "description": "Merge each Unit's range as one rebased Revision rather than replaying each upstream Revision.",
      "x-go-type-skip-optional-pointer": true
    },
    "Subgroup": {
      "type": "string",
      "description": "A category recorded on the Mutations of each Unit write. Alphanumeric, at most 64 characters, and not starting with ConfigHub.",
      "x-go-type-skip-optional-pointer": true
    },
    "TagID": {
      "type": "string",
      "description": "A Tag to put on the Revision each Unit the promotion writes is left at, clones included. Units the promotion leaves Unchanged are not tagged. Requires Use permission on the Tag, and cannot be used with ChangeOrderID, whose own Tags mark what it promotes. A selected Space with a Unit to write that the Tag already marks fails, and nothing in it is written.",
      "format": "uuid"
    },
    "TargetStage": {
      "type": "string",
      "description": "A Stage of the ChangeOrder's ChangeWorkflow to promote into. Requires a ChangeOrder with a ChangeWorkflow. When empty, and neither WhereSpace nor SpaceFilterID is given, the next Stage the change has not reached.",
      "x-go-type-skip-optional-pointer": true
    },
    "WhereSpace": {
      "type": "string",
      "description": "A where expression selecting the Spaces to promote. Intersected with the other selectors.",
      "x-go-type-skip-optional-pointer": true
    }
  },
  "$defs": {
    "Clearance": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ClearanceRequirement"
      }
    },
    "ClearanceRequirement": {
      "type": "object",
      "properties": {
        "Key": {
          "type": "string",
          "description": "The guard key this requirement is about",
          "x-go-type-skip-optional-pointer": true
        },
        "Operator": {
          "type": "string",
          "description": "Exists, In, NotIn, or DoesNotExist",
          "x-go-type-skip-optional-pointer": true
        },
        "Values": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The values In and NotIn compare against; unused by Exists and DoesNotExist",
          "x-go-type-skip-optional-pointer": true
        }
      }
    },
    "GuardStamp": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}