Document `crossplane resource validate --output` flag and programmatic validate API
- Dominant language
- SCSS
- Stars
- 60
- Forks
- 163
- Avg merge
- 15h 20m
- Merged PRs (30d)
- 9
Description
### What problem are you facing?
The CLI gains a `-o/--output text|json|yaml` flag on `crossplane resource validate` (per [crossplane/cli#62](https://github.com/crossplane/cli/issues/62)), and validate's logic is also exposed as a programmatic Go API for downstream consumers like [crossplane-diff](https://github.com/crossplane-contrib/crossplane-diff). The user-facing changes need documentation in [docs.crossplane.io](https://docs.crossplane.io).
This issue tracks the docs work for the corresponding cli PR (filed in tandem; will link once it's open against `crossplane/cli`).
### How could Crossplane help solve your problem?
Update the validate-related docs to cover:
**1. The new `--output` flag.**
- Default `text` is byte-identical to the historical output.
- `json` and `yaml` emit a structured payload with per-resource status and field-level error details (type, field path, message, bad value).
- Suggested example for the docs (mirrors the `--output json | jq` idiom in the new CLI help):
```shell
crossplane resource validate extensions.yaml resources.yaml --output json | jq '.summary'
```
- `--skip-success-results` is text-only; in JSON/YAML mode it's ignored (success entries remain in the structured payload so consumers filter themselves).
**2. The structured JSON/YAML schema** so users can write reliable filters/scripts:
```jsonc
{
"summary": { "total": 2, "valid": 1, "invalid": 1, "missingSchemas": 0 },
"resources": [
{
"apiVersion": "...", "kind": "...", "name": "...", "namespace": "...",
"status": "valid" | "invalid" | "missingSchema" | "defaultingFailed",
"errors": [
{
"type": "schema" | "cel" | "unknownField" | "defaulting",
"field": "spec.replicas",
"message": "...",
"value": "..."
}
]
}
]
}
```
**3. Programmatic Go API** (a contributor-facing note, possibly under contributing/integration docs rather than user docs).
The cli now ships a `cmd/crossplane/pkg/validate` package that returns a `*ValidationResult` directly, and a sibling `cmd/crossplane/pkg/validate/render` package that converts it to text/JSON/YAML. Tools that previously parsed validate's stdout (notably crossplane-diff) can switch to importing the Go API — worth a callout for downstream tool authors.
### Pointers
- Issue requesting the feature: crossplane/cli#62
- CLI help (will be updated as part of the cli PR): `cmd/crossplane/validate/help/validate.md`
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.