Add bundle manifest schema

Author: RamazanKara

CHANGELOG.md

@@ -35,6 +35,7 @@
 - Added `openexit run` to execute assessment, mapping, full generation, validation, status reporting, and optional evidence bundle export for collected projects.
 - Added `openexit demo` with embedded redacted fixtures for complete release-binary demos across supported assessment paths.
 - Added a machine-readable evidence bundle manifest with build metadata, validation summary, and per-file SHA-256 digests.
+- Added a public JSON Schema for evidence bundle manifests and test coverage that validates exported manifests against it.
 - Updated CI and release workflows to Node.js 24-native GitHub Actions.
 
 ## 0.1.0 - 2026-05-24

README.md

@@ -118,7 +118,7 @@ Included in the current implementation:
 - ArgoCD starter manifest.
 - Typed migration plan manifest and phase-gate Markdown plan.
 - Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, edge VCL/HAProxy/Coraza, and LiteLLM/vLLM candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
-- Evidence bundle export with README, checksums, and a machine-readable manifest.
+- Evidence bundle export with README, checksums, and a schema-backed machine-readable manifest.
 - Evidence bundle path-safety checks that reject symlinks in exported project sections.
 - No-op assist provider and explicit opt-in LiteLLM assist.
 - GitHub Enterprise to Forgejo assessment path with fixture import and live repository inventory collection.

docs/cli.md

@@ -29,7 +29,7 @@ The checked-in Datadog example can be refreshed with `make example VERSION=0.1.0
 
 `openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, identity realm/client candidate validation, edge VCL/HAProxy/Coraza candidate validation, LiteLLM/vLLM candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
 
-`openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree. Exported zips include `openexit-evidence/manifest.json` with build metadata, project source/target, validation totals, and per-file SHA-256 digests, plus `checksums.txt` for archive-level verification.
+`openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree. Exported zips include `openexit-evidence/manifest.json` with build metadata, project source/target, validation totals, and per-file SHA-256 digests, plus `checksums.txt` for archive-level verification. The manifest shape is published as `schemas/openexit.evidence-bundle.schema.json`.
 
 Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`; the identity path also supports `realm-client-candidate`; the edge path also supports `vcl-candidates`, `haproxy-candidates`, and `coraza-rule-candidates`; the AI provider path also supports `litellm-config-candidate`.
 

docs/release.md

@@ -17,7 +17,7 @@ Release-blocking v0.1 requirements:
 - Grafana, Prometheus, OpenTelemetry, and ArgoCD candidate generators.
 - Typed migration plan manifest with assessment, pilot, shadow, and cutover phase gates.
 - Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, edge VCL/HAProxy/Coraza, and LiteLLM/vLLM candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
-- Evidence bundle export with checksums, a machine-readable manifest, and OpenExit version metadata.
+- Evidence bundle export with checksums, a schema-backed machine-readable manifest, and OpenExit version metadata.
 - No-op AI assist and optional external assist behind explicit opt-in.
 - Documentation, examples, CI, release draft workflow, and reproducible release artifacts.
 
@@ -60,7 +60,7 @@ The AI provider path is complete for local fixture assessment workflows and incl
 - [ ] `validation/validation-report.md` includes `litellm-config-candidate: passed` for the OpenAI/Anthropic to vLLM/LiteLLM pipeline.
 - [ ] `CHANGELOG.md` has a `0.1.0` section.
 - [ ] Exported bundle README includes version, commit, build date, bundle timestamp, and candidate warning.
-- [ ] Exported bundle `manifest.json` includes build metadata, project source/target, validation totals, and per-file SHA-256 digests.
+- [ ] Exported bundle `manifest.json` includes build metadata, project source/target, validation totals, and per-file SHA-256 digests, and validates against `schemas/openexit.evidence-bundle.schema.json`.
 - [ ] Export refuses symlinks in exported project sections, including when `--force` is used.
 - [ ] No credentials, tokens, passwords, or private keys are present in fixtures, generated files, docs, or bundles.
 - [ ] Draft release notes have been reviewed.

docs/schemas.md

@@ -2,6 +2,8 @@
 
 OpenExit schemas live under `schemas/` and mirror the typed Go manifests. Release binaries embed these public Draft 7 JSON Schemas, and `openexit validate` checks project, inventory, assessment, mapping, migration-plan, and validation-report manifests against the embedded copies in addition to typed consistency checks and YAML/JSON parse checks.
 
+Evidence bundle exports include `openexit-evidence/manifest.json`, which follows `schemas/openexit.evidence-bundle.schema.json`. The manifest records OpenExit build metadata, project source/target metadata, validation totals, and SHA-256 digests for exported project files so downstream review tooling can verify a bundle without parsing every human-readable report first.
+
 Project manifests must use one of the supported source/target pairs: Datadog to Grafana LGTM, GitHub Enterprise to Forgejo, Okta/Auth0 to Keycloak/Zitadel, Cloudflare/Akamai to Varnish/HAProxy/Coraza, or OpenAI/Anthropic to vLLM/LiteLLM.
 
 Inventory dashboards can include optional `dataSources` and `templateVariables` fields so assessment can flag Grafana mapping risk. Datadog fixture and live collectors populate `metrics` from captured dashboard and monitor queries, including referenced tag keys where available. The live Datadog collector also populates `integrations` from the Datadog v2 Integrations API when accessible. SLOs can include optional `sli`, `burnRateMonitorIds`, and `dashboardRefs` fields. The top-level inventory `volumes` section records whether log and trace volume assumptions are known.

internal/app/e2e_test.go

@@ -11,6 +11,9 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	publicschemas "github.com/RamazanKara/openexit/schemas"
+	"github.com/santhosh-tekuri/jsonschema/v6"
 )
 
 func TestDefinitionOfDonePipelineAndBundle(t *testing.T) {
@@ -1208,6 +1211,9 @@ func verifyBundleManifest(files map[string][]byte) error {
 	if err := json.Unmarshal(data, &manifest); err != nil {
 		return err
 	}
+	if err := validateBundleManifestSchema(data); err != nil {
+		return err
+	}
 	if manifest.APIVersion != "openexit.dev/v1alpha1" || manifest.Kind != "EvidenceBundle" {
 		return &checksumError{message: "unexpected bundle manifest identity"}
 	}
@@ -1240,6 +1246,31 @@ func verifyBundleManifest(files map[string][]byte) error {
 	return nil
 }
 
+func validateBundleManifestSchema(data []byte) error {
+	schemaData, err := publicschemas.FS.ReadFile("openexit.evidence-bundle.schema.json")
+	if err != nil {
+		return err
+	}
+	compiler := jsonschema.NewCompiler()
+	compiler.DefaultDraft(jsonschema.Draft7)
+	document, err := jsonschema.UnmarshalJSON(bytes.NewReader(schemaData))
+	if err != nil {
+		return err
+	}
+	if err := compiler.AddResource("openexit.evidence-bundle.schema.json", document); err != nil {
+		return err
+	}
+	schema, err := compiler.Compile("openexit.evidence-bundle.schema.json")
+	if err != nil {
+		return err
+	}
+	instance, err := jsonschema.UnmarshalJSON(bytes.NewReader(data))
+	if err != nil {
+		return err
+	}
+	return schema.Validate(instance)
+}
+
 func verifyChecksums(files map[string][]byte) error {
 	checksumData, ok := files["openexit-evidence/checksums.txt"]
 	if !ok {

schemas/openexit.evidence-bundle.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openexit.dev/schemas/openexit.evidence-bundle.schema.json",
+  "title": "OpenExit Evidence Bundle Manifest",
+  "type": "object",
+  "required": ["apiVersion", "kind", "generatedAt", "build", "project", "validation", "files"],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": { "const": "openexit.dev/v1alpha1" },
+    "kind": { "const": "EvidenceBundle" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "build": {
+      "type": "object",
+      "required": ["version", "commit", "date"],
+      "additionalProperties": false,
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "commit": { "type": "string", "minLength": 1 },
+        "date": { "type": "string", "minLength": 1 }
+      }
+    },
+    "project": {
+      "type": "object",
+      "required": ["name", "source", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "source": { "type": "string" },
+        "target": { "type": "string" }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "required": ["status", "checks", "passed", "failed", "warnings"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "enum": ["passed", "failed"] },
+        "checks": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["path", "size", "sha256"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/].*"
+          },
+          "size": { "type": "integer", "minimum": 0 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        }
+      }
+    }
+  }
+}