crossplane / crossplane/docs

Document `crossplane resource validate --output` flag and programmatic validate API

Open
#1,101 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.