#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
#  SPDX-License-Identifier: Apache-2.0
$schema: "https://json-schema.org/draft-07/schema#"
$id: "mas/v1#overlay"
title: "Overlay Manifest"
description: >
  Schema for kind: Overlay manifests (apiVersion: mas/v1). An overlay is a partial
  manifest applied on top of Agent, MAS, or Flavour configuration for a specific
  experimental or deployment condition (RFC 7396 JSON Merge Patch under spec.patch).
  Validate with:
  python -m jsonschema --instance overlays/baseline.yaml overlay.schema.yaml
type: object
required:
  - apiVersion
  - kind
  - metadata
  - spec
additionalProperties: false
patternProperties:
  "^x-":
    description: "Extension properties (UI metadata, canvas state, etc.) — ignored by the runtime."
properties:
  apiVersion:
    type: string
    const: "mas/v1"

  kind:
    type: string
    const: "Overlay"

  metadata:
    type: object
    additionalProperties: false
    patternProperties:
      "^x-":
        description: "Extension properties (UI metadata, canvas state, etc.) — ignored by the runtime."
    properties:
      name:
        type: string
        description: "Patch identifier — also the stem of the YAML file (e.g. baseline)."
        default: ""
      id:
        type: string
        description: "Alternative patch identifier (lab-style). Mutually exclusive with name."
        default: ""
      description:
        type: string
        default: ""
      namespace:
        type: string
        description: "Namespace scope for the overlay (global or app name). Defaults to global."
        default: "global"
      x-namespace:
        type: string
        description: "UI namespace hint (global or application id). Ignored by the runtime."

  spec:
    type: object
    description: "Patch spec: target selector, patch payload, and optional
      agent-level fields."
    additionalProperties: false
    required:
      - target
      - patch
    properties:
      tools:
        type: array
        description: >
          Agent tools injected for this scenario (merged via
          merge_agent_overlay). Accepts semantic names (strings) or ref/inline
          objects.
        default: []
        items:
          oneOf:
            - type: string
            - type: object
              additionalProperties: false
              required: [ref]
              properties:
                ref:
                  type: string

      target:
        type: object
        description: "Selects which resource this patch applies to."
        additionalProperties: false
        required:
          - kind
        properties:
          kind:
            type: string
            description: "Resource kind: MAS | Flavour | Agent | Infra | Experiment | Workspace"
            enum: [Agent, MAS, Flavour, Infra, Experiment, Workspace]
          name:
            type: string
            description: >
              Optional name filter. On an Agent overlay applied to a MAS,
              selects one nested agency row (id, name, or metadata.name).
              Omit to fan the patch out to every nested agent. Zero matches
              is an error.

      patch:
        description: >
          Patch payload. Validation is target-aware: Agent overlays accept
          agent-patch fields, MAS overlays accept MAS-patch fields, and Flavour
          overlays accept deployment-posture fields only.
        type: object

      overrides:
        type: array
        description: >
          Ordered session-tree path assignments applied after patch. Uses the
          same type/id selector syntax as the CLI --override option.
        items:
          type: string

    allOf:
      - if:
          required: [target]
          properties:
            target:
              type: object
              required: [kind]
              properties:
                kind:
                  const: "Agent"
        then:
          properties:
            patch:
              $ref: "./fragments/overlay-agent-patch.schema.yaml"
      - if:
          required: [target]
          properties:
            target:
              type: object
              required: [kind]
              properties:
                kind:
                  const: "MAS"
        then:
          properties:
            patch:
              $ref: "./fragments/overlay-mas-patch.schema.yaml"
      - if:
          required: [target]
          properties:
            target:
              type: object
              required: [kind]
              properties:
                kind:
                  const: "Flavour"
        then:
          properties:
            patch:
              $ref: "./fragments/overlay-flavour-patch.schema.yaml"
      - if:
          required: [target]
          properties:
            target:
              type: object
              required: [kind]
              properties:
                kind:
                  const: "Infra"
        then:
          properties:
            patch:
              $ref: "./fragments/overlay-infra-patch.schema.yaml"