{
  "openapi": "3.1.0",
  "info": {
    "title": "Bundle Manifest Specification API",
    "version": "1.0.0",
    "description": "OpenAPI 3.1 schema representation for Bundle Manifest (bundle.manifest.json)"
  },
  "paths": {
    "/api/v1/bundlemanifest/validate": {
      "post": {
        "summary": "Validate BundleManifest Payload",
        "description": "Validates an arbitrary payload against the BundleManifest schema contract.",
        "operationId": "validateBundleManifest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BundleManifest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation passed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "valid"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed with schema constraint errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean",
                      "const": false
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "valid",
                    "errors"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BundleManifest": {
        "title": "BundleManifest",
        "description": "Declarative configuration schema for @spec-platform/meta-bundler",
        "type": "object",
        "properties": {
          "$schema": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "context": {
            "description": "Ambient background context, metadata, prompt, and documentation",
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "docs": {
                "type": "array",
                "items": {
                  "description": "Ambient background context document mapping",
                  "type": "object",
                  "properties": {
                    "dest": {
                      "type": "string"
                    },
                    "exclude": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "source": {
                      "description": "Source path or glob pattern",
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "source"
                  ]
                }
              },
              "domain": {
                "type": "string"
              },
              "generateContextDoc": {
                "type": "boolean",
                "default": true
              },
              "issue": {
                "type": "string"
              },
              "metadata": {
                "type": "object",
                "additionalProperties": {}
              },
              "persona": {
                "type": "string"
              },
              "prerequisites": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "prompt": {
                "type": "string"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "template": {
                "type": "string"
              }
            }
          },
          "deduplicate": {
            "description": "Deduplication and collision resolution rules",
            "type": "object",
            "properties": {
              "byContentHash": {
                "type": "boolean",
                "default": true
              },
              "byPath": {
                "type": "string",
                "enum": [
                  "error",
                  "overwrite",
                  "warn-overwrite"
                ],
                "default": "warn-overwrite"
              }
            }
          },
          "description": {
            "type": "string"
          },
          "exclude": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "format": {
            "type": "string",
            "enum": [
              "directory",
              "zip"
            ],
            "default": "zip"
          },
          "linkResolution": {
            "description": "Markdown and TypeSpec reference link resolution configuration",
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": true
              },
              "gitRepositoryUrl": {
                "type": "string"
              },
              "normalizeFileSchemes": {
                "type": "boolean",
                "default": true
              },
              "rewriteRelativeLinks": {
                "type": "boolean",
                "default": true
              },
              "unbundledPolicy": {
                "type": "string",
                "enum": [
                  "error",
                  "github-fallback",
                  "preserve",
                  "warn"
                ],
                "default": "warn"
              }
            }
          },
          "lockfileMode": {
            "type": "string",
            "enum": [
              "consolidated",
              "split"
            ],
            "default": "consolidated"
          },
          "name": {
            "description": "Identifier name for the bundle",
            "type": "string",
            "minLength": 1
          },
          "output": {
            "description": "Output zip archive or directory path relative to manifest",
            "type": "string",
            "minLength": 1
          },
          "phase": {
            "type": "string",
            "enum": [
              "develop",
              "fix",
              "review",
              "test"
            ]
          },
          "scope": {
            "description": "Declarative extraction scope and domain boundary configuration",
            "type": "object",
            "properties": {
              "categoryFidelity": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "enum": [
                    "contract-only",
                    "full",
                    "summary"
                  ]
                }
              },
              "direction": {
                "type": "string",
                "enum": [
                  "bidirectional",
                  "downstream",
                  "upstream"
                ],
                "default": "downstream"
              },
              "entrypoints": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "excludeCategories": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "convention",
                    "error",
                    "feature",
                    "issue",
                    "mechanism"
                  ]
                }
              },
              "include": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "includeCategories": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "convention",
                    "error",
                    "feature",
                    "issue",
                    "mechanism"
                  ]
                }
              },
              "maxDepth": {
                "type": "integer",
                "exclusiveMinimum": 0
              },
              "preserveTargets": {
                "type": "boolean",
                "default": true
              },
              "sections": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "stopAt": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "traversalMode": {
                "type": "string",
                "enum": [
                  "explicit",
                  "hybrid",
                  "reachability"
                ],
                "default": "hybrid"
              },
              "upstreamDepth": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "default": 1
              }
            }
          },
          "targets": {
            "description": "Declarative list of target file mappings",
            "type": "array",
            "items": {
              "description": "Target file mapping declaration",
              "type": "object",
              "properties": {
                "dest": {
                  "description": "Destination directory or file path inside bundle",
                  "type": "string",
                  "minLength": 1
                },
                "exclude": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "source": {
                  "description": "Source file path or glob pattern relative to manifest directory",
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "dest",
                "source"
              ]
            },
            "minItems": 1
          },
          "topics": {
            "type": "object",
            "additionalProperties": {
              "description": "Declarative named topic profile",
              "type": "object",
              "properties": {
                "author": {
                  "type": "string"
                },
                "context": {
                  "description": "Ambient background context, metadata, prompt, and documentation",
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "array",
                      "items": {
                        "description": "Ambient background context document mapping",
                        "type": "object",
                        "properties": {
                          "dest": {
                            "type": "string"
                          },
                          "exclude": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "source": {
                            "description": "Source path or glob pattern",
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "source"
                        ]
                      }
                    },
                    "domain": {
                      "type": "string"
                    },
                    "generateContextDoc": {
                      "type": "boolean",
                      "default": true
                    },
                    "issue": {
                      "type": "string"
                    },
                    "metadata": {
                      "type": "object",
                      "additionalProperties": {}
                    },
                    "persona": {
                      "type": "string"
                    },
                    "prerequisites": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "prompt": {
                      "type": "string"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "template": {
                      "type": "string"
                    }
                  }
                },
                "deduplicate": {
                  "description": "Deduplication and collision resolution rules",
                  "type": "object",
                  "properties": {
                    "byContentHash": {
                      "type": "boolean",
                      "default": true
                    },
                    "byPath": {
                      "type": "string",
                      "enum": [
                        "error",
                        "overwrite",
                        "warn-overwrite"
                      ],
                      "default": "warn-overwrite"
                    }
                  }
                },
                "description": {
                  "type": "string"
                },
                "exclude": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "format": {
                  "type": "string",
                  "enum": [
                    "directory",
                    "zip"
                  ]
                },
                "linkResolution": {
                  "description": "Markdown and TypeSpec reference link resolution configuration",
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean",
                      "default": true
                    },
                    "gitRepositoryUrl": {
                      "type": "string"
                    },
                    "normalizeFileSchemes": {
                      "type": "boolean",
                      "default": true
                    },
                    "rewriteRelativeLinks": {
                      "type": "boolean",
                      "default": true
                    },
                    "unbundledPolicy": {
                      "type": "string",
                      "enum": [
                        "error",
                        "github-fallback",
                        "preserve",
                        "warn"
                      ],
                      "default": "warn"
                    }
                  }
                },
                "output": {
                  "type": "string"
                },
                "phase": {
                  "type": "string",
                  "enum": [
                    "develop",
                    "fix",
                    "review",
                    "test"
                  ]
                },
                "scope": {
                  "description": "Declarative extraction scope and domain boundary configuration",
                  "type": "object",
                  "properties": {
                    "categoryFidelity": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "enum": [
                          "contract-only",
                          "full",
                          "summary"
                        ]
                      }
                    },
                    "direction": {
                      "type": "string",
                      "enum": [
                        "bidirectional",
                        "downstream",
                        "upstream"
                      ],
                      "default": "downstream"
                    },
                    "entrypoints": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "exclude": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "excludeCategories": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "convention",
                          "error",
                          "feature",
                          "issue",
                          "mechanism"
                        ]
                      }
                    },
                    "include": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "includeCategories": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "convention",
                          "error",
                          "feature",
                          "issue",
                          "mechanism"
                        ]
                      }
                    },
                    "maxDepth": {
                      "type": "integer",
                      "exclusiveMinimum": 0
                    },
                    "preserveTargets": {
                      "type": "boolean",
                      "default": true
                    },
                    "sections": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "stopAt": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "traversalMode": {
                      "type": "string",
                      "enum": [
                        "explicit",
                        "hybrid",
                        "reachability"
                      ],
                      "default": "hybrid"
                    },
                    "upstreamDepth": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "default": 1
                    }
                  }
                },
                "targets": {
                  "description": "List of target file mappings designated for this topic",
                  "type": "array",
                  "items": {
                    "description": "Target file mapping declaration",
                    "type": "object",
                    "properties": {
                      "dest": {
                        "description": "Destination directory or file path inside bundle",
                        "type": "string",
                        "minLength": 1
                      },
                      "exclude": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "description": "Source file path or glob pattern relative to manifest directory",
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "required": [
                      "dest",
                      "source"
                    ]
                  }
                },
                "treeShake": {
                  "description": "Declarative tree-shaking reachability configuration",
                  "type": "object",
                  "properties": {
                    "categoryFidelity": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "enum": [
                          "contract-only",
                          "full",
                          "summary"
                        ]
                      }
                    },
                    "direction": {
                      "type": "string",
                      "enum": [
                        "bidirectional",
                        "downstream",
                        "upstream"
                      ],
                      "default": "downstream"
                    },
                    "enabled": {
                      "type": "boolean",
                      "default": false
                    },
                    "entrypoints": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "excludeCategories": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "convention",
                          "error",
                          "feature",
                          "issue",
                          "mechanism"
                        ]
                      }
                    },
                    "includeCategories": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "convention",
                          "error",
                          "feature",
                          "issue",
                          "mechanism"
                        ]
                      }
                    },
                    "maxDepth": {
                      "type": "integer",
                      "exclusiveMinimum": 0
                    },
                    "preserve": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "preserveTargets": {
                      "type": "boolean",
                      "default": true
                    },
                    "reportEliminated": {
                      "type": "boolean",
                      "default": true
                    },
                    "scope": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "stopAt": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "traversalMode": {
                      "type": "string",
                      "enum": [
                        "explicit",
                        "hybrid",
                        "reachability"
                      ],
                      "default": "hybrid"
                    },
                    "upstreamDepth": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "default": 1
                    }
                  }
                }
              },
              "required": [
                "targets"
              ]
            }
          },
          "treeShake": {
            "description": "Declarative tree-shaking reachability configuration",
            "type": "object",
            "properties": {
              "categoryFidelity": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "enum": [
                    "contract-only",
                    "full",
                    "summary"
                  ]
                }
              },
              "direction": {
                "type": "string",
                "enum": [
                  "bidirectional",
                  "downstream",
                  "upstream"
                ],
                "default": "downstream"
              },
              "enabled": {
                "type": "boolean",
                "default": false
              },
              "entrypoints": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "excludeCategories": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "convention",
                    "error",
                    "feature",
                    "issue",
                    "mechanism"
                  ]
                }
              },
              "includeCategories": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "convention",
                    "error",
                    "feature",
                    "issue",
                    "mechanism"
                  ]
                }
              },
              "maxDepth": {
                "type": "integer",
                "exclusiveMinimum": 0
              },
              "preserve": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "preserveTargets": {
                "type": "boolean",
                "default": true
              },
              "reportEliminated": {
                "type": "boolean",
                "default": true
              },
              "scope": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "stopAt": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "traversalMode": {
                "type": "string",
                "enum": [
                  "explicit",
                  "hybrid",
                  "reachability"
                ],
                "default": "hybrid"
              },
              "upstreamDepth": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "default": 1
              }
            }
          },
          "version": {
            "description": "Semantic version of the bundle",
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "name",
          "output",
          "targets",
          "version"
        ]
      }
    }
  }
}