From 73a438d31b3a07e9d88f08b3a275ba89e5a0ef74 Mon Sep 17 00:00:00 2001 From: Kastriot Salihu Date: Fri, 22 May 2026 11:11:23 +0200 Subject: [PATCH 1/2] SP-141: surface BUSINESS validation layer in config validate help and docs Document the BUSINESS validation layer in `config validate` so it is discoverable from `--help` and the user guide instead of requiring prior knowledge of the pacman API. - module.ts: `--layers` help now enumerates the allowed values (SCHEMA, BUSINESS) and notes that they can be combined. - config-commands.md: new "Validate Package Configurations" section covering `--layers`, `--nodeKeys`, console output, and the JSON report shape; new "Validate During Import" subsection clarifying that `config import --validate` runs SCHEMA only. - agentic-development-guide.md: agent step now mentions that import-time validation is SCHEMA-only and shows `config validate --layers SCHEMA BUSINESS` as the way to run business rules. - asset-registry-endpoints SKILL: same clarification for agents plus a Quick reference entry for `config validate`. Default behaviour and CLI surface are unchanged; this only adds help text and docs. Includes-AI-Code: true Co-authored-by: Cursor --- .../skills/asset-registry-endpoints/SKILL.md | 56 +++++++++-- docs/user-guide/agentic-development-guide.md | 8 +- docs/user-guide/config-commands.md | 97 +++++++++++++++++++ .../configuration-management/module.ts | 6 +- 4 files changed, 155 insertions(+), 12 deletions(-) diff --git a/.cursor/skills/asset-registry-endpoints/SKILL.md b/.cursor/skills/asset-registry-endpoints/SKILL.md index 27e4f18..cf56f84 100644 --- a/.cursor/skills/asset-registry-endpoints/SKILL.md +++ b/.cursor/skills/asset-registry-endpoints/SKILL.md @@ -77,9 +77,13 @@ export_/ $CLI config import -d --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,48 @@ build-from-options flags. $CLI asset-registry validate --assetType -f request.json -p ``` -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 --validate --overwrite -p ``` -**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 --layers SCHEMA BUSINESS -p +``` + +- `--layers SCHEMA BUSINESS` runs both layers in a single request. Supported + values today are `SCHEMA` and `BUSINESS`. +- `--nodeKeys ` (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] +``` + +There is a small race between `config import` and `config validate`: the +newly-imported staging version may take ~2–3 seconds to become queryable. +If a `config validate` run returns the previous version's results, wait a +moment and retry. + +**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 +386,5 @@ $CLI config import -d --validate --overwrite -p | `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 --validate --overwrite` | Validate and import packages | +| `config import -d --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 | diff --git a/docs/user-guide/agentic-development-guide.md b/docs/user-guide/agentic-development-guide.md index 6ba5b71..f146b73 100644 --- a/docs/user-guide/agentic-development-guide.md +++ b/docs/user-guide/agentic-development-guide.md @@ -82,12 +82,18 @@ content-cli asset-registry validate --assetType \ --packageKey --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 --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 --layers SCHEMA BUSINESS +``` + If validation returns errors, fix the issues before importing. ### 6. Import diff --git a/docs/user-guide/config-commands.md b/docs/user-guide/config-commands.md index ebb59d2..bdb099c 100644 --- a/docs/user-guide/config-commands.md +++ b/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 -d --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 +``` + +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 --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 --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 --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 diff --git a/src/commands/configuration-management/module.ts b/src/commands/configuration-management/module.ts index 8a80e0c..9e9e0e7 100644 --- a/src/commands/configuration-management/module.ts +++ b/src/commands/configuration-management/module.ts @@ -63,7 +63,11 @@ class Module extends IModule { configCommand.command("validate") .description("Validate package node configurations") .requiredOption("--packageKey ", "Key of the package to validate") - .option("--layers ", "Validation layers to run", ["SCHEMA"]) + .option( + "--layers ", + "Validation layers to run. Allowed values: SCHEMA, BUSINESS (can be combined, e.g. --layers SCHEMA BUSINESS). Defaults to SCHEMA.", + ["SCHEMA"] + ) .option("--nodeKeys ", "Specific node keys to validate (default: all nodes)") .option("--json", "Return the response as a JSON file") .action(this.validatePackage); From 66b0e5863f8d79908917a2df4555f8b13b3e69be Mon Sep 17 00:00:00 2001 From: Kastriot Salihu Date: Fri, 22 May 2026 13:20:06 +0200 Subject: [PATCH 2/2] =?UTF-8?q?SP-141:=20drop=20import=E2=86=94validate=20?= =?UTF-8?q?race=20note=20from=20the=20asset-registry=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The note about the ~2–3s window where a freshly-imported staging version isn't yet queryable by the validate endpoint is being tracked as a separate concern. Removing it from the skill so the documentation doesn't lock the behaviour in before the bug fix lands. Includes-AI-Code: true Co-authored-by: Cursor --- .cursor/skills/asset-registry-endpoints/SKILL.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.cursor/skills/asset-registry-endpoints/SKILL.md b/.cursor/skills/asset-registry-endpoints/SKILL.md index cf56f84..6e458f5 100644 --- a/.cursor/skills/asset-registry-endpoints/SKILL.md +++ b/.cursor/skills/asset-registry-endpoints/SKILL.md @@ -322,11 +322,6 @@ info: info: ERROR my-kpi-model (SEMANTIC_MODEL) - Data Model should not be empty [dataModelId.empty] ``` -There is a small race between `config import` and `config validate`: the -newly-imported staging version may take ~2–3 seconds to become queryable. -If a `config validate` run returns the previous version's results, wait a -moment and retry. - **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