From 22468c9de4c1cb30a8805d146fb014452c35ef84 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Wed, 10 Jun 2026 19:32:36 +0000
Subject: [PATCH] docs: document per-block validation and legacy addon warning
 for porter apply

---
 .../configuration-as-code/addons-porter-yaml.mdx     | 11 +++++++++++
 standard/cli/command-reference/porter-apply.mdx      | 12 ++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/applications/configuration-as-code/addons-porter-yaml.mdx b/applications/configuration-as-code/addons-porter-yaml.mdx
index ef60f42..5ac3599 100644
--- a/applications/configuration-as-code/addons-porter-yaml.mdx
+++ b/applications/configuration-as-code/addons-porter-yaml.mdx
@@ -98,3 +98,14 @@ addons:
         ramMegabytes: 110
 ```
 
+## Validating multi-app/addon porter.yaml
+
+Run `porter apply validate` (or `porter apply --validate`) to check a multi-app/addon `porter.yaml` before deploying. Each app and addon block under `apps:` and `addons:` is split out and validated individually, and the command fails on the first invalid block and reports its index in the array.
+
+```bash
+porter apply validate -f porter.yaml
+```
+
+<Warning>
+Addon blocks that use the deprecated legacy schema are skipped during validation and print a yellow `DEPRECATION WARNING`. The command still succeeds for the rest of the file, but legacy addon support will be removed in a future release. Update those addons to the current schema so they're covered by validation.
+</Warning>
diff --git a/standard/cli/command-reference/porter-apply.mdx b/standard/cli/command-reference/porter-apply.mdx
index 05db14b..82109bd 100644
--- a/standard/cli/command-reference/porter-apply.mdx
+++ b/standard/cli/command-reference/porter-apply.mdx
@@ -78,6 +78,12 @@ You can pass environment variables and secrets directly via command-line flags w
 | `--validate` | Check that the `porter.yaml` file is valid YAML syntax |
 | `--dry-run` | Perform server-side validation to confirm the configuration is valid without applying changes |
 
+When you pass `--validate` (or run `porter apply validate`), Porter validates the file based on its format:
+
+- **Single-app `porter.yaml`** — validated as one application configuration.
+- **Multi-app/addon `porter.yaml`** (top-level `apps:` and/or `addons:` arrays) — each app and addon block is split out and validated individually. The command fails on the first invalid app or addon and reports its index in the array.
+- **Legacy addon schemas** — addon blocks that use the deprecated legacy schema are skipped with a yellow `DEPRECATION WARNING`. Validation still succeeds for the rest of the file, but support for the legacy schema will be removed in a future release. Update the addon to the current schema to keep it covered by validation.
+
 ### Advanced Options
 
 | Flag | Short | Description |
@@ -122,6 +128,12 @@ porter apply -f porter.yaml --preview
 porter apply -f porter.yaml --validate
 ```
 
+```bash Validate Multi-App/Addon YAML
+# Validate every app and addon block in a multi-app porter.yaml individually.
+# Legacy addon blocks are skipped with a deprecation warning.
+porter apply validate -f porter.yaml
+```
+
 ```bash Dry Run
 # Validate the full configuration server-side without deploying
 porter apply -f porter.yaml --dry-run