SP-141: Document BUSINESS validation layer (#355)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ksalihu

.cursor/skills/asset-registry-endpoints/SKILL.md

@@ -77,9 +77,13 @@ export_<uuid>/
 $CLI config import -d <export_dir> --validate --overwrite
 ```
 
-- `--validate` — performs schema validations before importing. If there are
-  validation errors the import is **not** performed and the errors are returned.
-  If there are no errors, the package and its assets are imported normally.
+- `--validate` — performs **SCHEMA-layer** validation on each node before
+  importing. If there are validation errors the import is **not** performed and
+  the errors are returned. If there are no errors, the package and its assets
+  are imported normally. To also run **BUSINESS-layer** rules (e.g. PQL
+  parsing, data-model availability, KPI uniqueness for Knowledge Models), run
+  `config validate --layers SCHEMA BUSINESS` against the imported staging
+  version — see *Validating an imported package* below.
 - `--overwrite` — required when updating an existing package
 - Without `--overwrite` — creates a **new** package (use for first-time import)
 
@@ -286,17 +290,43 @@ build-from-options flags.
 $CLI asset-registry validate --assetType <ASSET_TYPE> -f request.json -p <profile>
 ```
 
-You can also validate during import with `config import --validate`:
+You can also validate during import with `config import --validate` — this
+runs the SCHEMA layer only:
 
 ```bash
 $CLI config import -d <export_dir> --validate --overwrite -p <profile>
 ```
 
-**Important**: If validation returns errors, do **not** proceed with the import.
-Instead, fix the schema violations in the node JSON and re-validate. If you
-cannot resolve the errors automatically, present the validation results to the
-user and ask whether they want to continue importing with invalid configuration
-or stop to fix it manually.
+### Validating an imported package
+
+To run **business-layer** rules against the staging version of a package (e.g.
+PQL parsing, data-model availability, KPI uniqueness for `SEMANTIC_MODEL`),
+use `config validate`:
+
+```bash
+$CLI config validate --packageKey <pkg> --layers SCHEMA BUSINESS -p <profile>
+```
+
+- `--layers SCHEMA BUSINESS` runs both layers in a single request. Supported
+  values today are `SCHEMA` and `BUSINESS`.
+- `--nodeKeys <key1> <key2>` (optional) restricts validation to specific nodes.
+- `--json` writes the full structured report to a file in the current working
+  directory instead of printing to the console.
+
+The console output prints a summary plus one line per finding:
+
+```
+info:    Validation result: INVALID
+info:    Errors: 1 | Warnings: 0 | Info: 0
+info:
+info:      ERROR   my-kpi-model (SEMANTIC_MODEL) - Data Model should not be empty [dataModelId.empty]
+```
+
+**Important**: If validation returns errors, do **not** proceed with the
+import. Instead, fix the schema or business-rule violations in the node JSON
+and re-validate. If you cannot resolve the errors automatically, present the
+validation results to the user and ask whether they want to continue importing
+with invalid configuration or stop to fix it manually.
 
 ## Troubleshooting
 
@@ -351,4 +381,5 @@ $CLI config import -d <export_dir> --validate --overwrite -p <profile>
 | `asset-registry methodology --assetType X` | Get methodology / best-practices (if available) |
 | `config list` | List packages |
 | `config export --packageKeys X --unzip` | Export packages |
-| `config import -d <dir> --validate --overwrite` | Validate and import packages |
+| `config import -d <dir> --validate --overwrite` | Validate (SCHEMA only) and import packages |
+| `config validate --packageKey P --layers SCHEMA BUSINESS` | Validate a package's staging version against the SCHEMA and/or BUSINESS layers |

docs/user-guide/agentic-development-guide.md

@@ -82,12 +82,18 @@ content-cli asset-registry validate --assetType <ASSET_TYPE> \
   --packageKey <package-key> --configuration '{ ... }'
 ```
 
-Or validate during import with the `--validate` flag:
+Or validate during import with the `--validate` flag — note that this runs the `SCHEMA` layer only:
 
 ```bash
 content-cli config import -d <export_dir> --validate --overwrite
 ```
 
+To also run business-layer rules (PQL parsing, data-model availability, KPI uniqueness, …), run `config validate` against the just-imported staging version:
+
+```bash
+content-cli config validate --packageKey <package-key> --layers SCHEMA BUSINESS
+```
+
 If validation returns errors, fix the issues before importing.
 
 ### 6. Import

docs/user-guide/config-commands.md

@@ -167,6 +167,103 @@ Finally, the result of this command will be a list of PostPackageImportData expo
 info:    Config import report file: 9560f81f-f746-4117-83ee-dd1f614ad624.json
 ```
 
+### Validate During Import
+
+Add `--validate` to `config import` to run validation against each node **before** the import is committed:
+
+```bash
+content-cli config import -p <sourceProfile> -d <export_dir> --validate --overwrite
+```
+
+`config import --validate` runs the **SCHEMA** layer only. It does **not** run BUSINESS-layer checks (PQL parsing, data-model availability, KPI uniqueness, etc.). To run business validation, use [`config validate`](#validate-package-configurations) after the import.
+
+## Validate Package Configurations
+
+The `config validate` command validates the **staging (draft) version** of a package by sending its nodes through one or more validation layers. The command runs against the Pacman validate API and returns a structured report of errors, warnings, and info findings.
+
+This command requires **edit permission** on the target package (see [Permissions](#permissions)).
+
+```bash
+content-cli config validate --packageKey <packageKey>
+```
+
+By default, only the `SCHEMA` layer is run. The console output looks like:
+
+```bash
+info:    Validation result: VALID
+info:    Errors: 0 | Warnings: 0 | Info: 0
+```
+
+If there are findings, each one is printed on its own line with the severity, node key, asset type, message, and code:
+
+```bash
+info:    Validation result: INVALID
+info:    Errors: 1 | Warnings: 0 | Info: 0
+info:
+info:      ERROR   my-knowledge-model (SEMANTIC_MODEL) - $.requiredField: is missing but it is required [REQUIRED_PROPERTY_MISSING]
+```
+
+### Validation Layers
+
+The `--layers` option selects which validation layers to run. Multiple layers can be passed and are executed in a single request; their findings are merged into one report.
+
+| Layer | What it checks | Owner |
+|---|---|---|
+| `SCHEMA` | Asset-schema conformance of each node's `configuration` field — required properties, enum values, type checks, conditional schemas. | Asset registry |
+| `BUSINESS` | Asset-type-specific business rules — for `SEMANTIC_MODEL`, e.g. PQL parsing, data-model availability, KPI uniqueness. Rules live in the owning asset service. | Owning asset service (e.g. `cloud-semantic-layer` for Knowledge Models) |
+
+Currently `SCHEMA` and `BUSINESS` are the only layers accepted by the Pacman API. Other values are rejected with a `400 layers.unsupported` error.
+
+To run both layers:
+
+```bash
+content-cli config validate --packageKey <packageKey> --layers SCHEMA BUSINESS
+```
+
+### Validate Specific Nodes
+
+By default, every node in the package's staging version is validated. To restrict the scope to a subset of nodes, use `--nodeKeys`:
+
+```bash
+content-cli config validate --packageKey <packageKey> --nodeKeys node-key-1 node-key-2
+```
+
+### Export Validation Report as JSON
+
+Use `--json` to write the full validation report to a JSON file in the current working directory instead of printing it to the console:
+
+```bash
+content-cli config validate --packageKey <packageKey> --layers SCHEMA BUSINESS --json
+```
+
+The filename is printed on success:
+
+```bash
+info:    Validation report file: config_validate_report_9560f81f-f746-4117-83ee-dd1f614ad624.json
+```
+
+The JSON report has the shape:
+
+```typescript
+interface ValidationReport {
+    packageKey: string;
+    valid: boolean;
+    summary: { errors: number; warnings: number; info: number };
+    results: ValidationResult[];
+}
+
+interface ValidationResult {
+    layer: "SCHEMA" | "BUSINESS";
+    severity: "ERROR" | "WARNING" | "INFO";
+    nodeKey: string;
+    assetType: string;
+    path: string;
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+```
+
 ## Listing & Mapping Variables
 
 ### Listing Package Variables

src/commands/configuration-management/module.ts

@@ -63,7 +63,11 @@ class Module extends IModule {
         configCommand.command("validate")
             .description("Validate package node configurations")
             .requiredOption("--packageKey <packageKey>", "Key of the package to validate")
-            .option("--layers <layers...>", "Validation layers to run", ["SCHEMA"])
+            .option(
+                "--layers <layers...>",
+                "Validation layers to run. Allowed values: SCHEMA, BUSINESS (can be combined, e.g. --layers SCHEMA BUSINESS). Defaults to SCHEMA.",
+                ["SCHEMA"]
+            )
             .option("--nodeKeys <nodeKeys...>", "Specific node keys to validate (default: all nodes)")
             .option("--json", "Return the response as a JSON file")
             .action(this.validatePackage);