Skip to content

docs: document CLI write support for content verification #563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
torimwhaley merged 2 commits into from
Apr 23, 2026
Merged

docs: document CLI write support for content verification #563

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
52dc3b9
docs: document CLI write support for content verification
torimwhaley Apr 22, 2026
247b2cd
docs: remove example workflow section from verified-content
torimwhaley Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion guides/developer/dashboards-as-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,18 @@ slug: my-cool-dashboard
spaceSlug: my-space
version: 1
downloadedAt: "2025-01-02T10:15:47.406Z"
# Verification fields (only present if the dashboard has been verified):
verification:
# Read-only audit info, ignored on upload.
verifiedAt: "2025-01-02T09:30:00.000Z"
verifiedBy:
firstName: David
lastName: Attenborough
userUuid: b264d83a-9000-426a-85ec-3f9c20f368ce
verified: true
# `verified` is the writable flag. Set to true/false to verify/unverify on upload,
# or omit to leave verification state unchanged.
# See /guides/verified-content for full semantics.
```

### Charts
Expand Down Expand Up @@ -565,7 +577,18 @@ tableConfig:
spaceSlug: my-space
version: 1
downloadedAt: "2025-04-09T10:44:01.104Z"

# Verification fields (only present if the chart has been verified):
verification:
# Read-only audit info, ignored on upload.
verifiedAt: "2025-04-09T08:15:00.000Z"
verifiedBy:
firstName: David
lastName: Attenborough
userUuid: b264d83a-9000-426a-85ec-3f9c20f368ce
verified: true
# `verified` is the writable flag. Set to true/false to verify/unverify on upload,
# or omit to leave verification state unchanged.
# See /guides/verified-content for full semantics.
```

<Warning>
Expand Down
45 changes: 39 additions & 6 deletions guides/verified-content.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,45 @@ This guarantees that a verified badge always reflects content that an admin has

## Verification in charts and dashboards as code

Verification status is included in [charts and dashboards as code](/guides/developer/dashboards-as-code). When you run `lightdash download`, verified content includes verification metadata right in the YAML, so you can see which downloaded files represent approved content.
Verification status is included in [charts and dashboards as code](/guides/developer/dashboards-as-code). When you run `lightdash download`, verified content includes verification metadata in the YAML, and `lightdash upload` can apply or remove the verified badge based on what your YAML says.

<Note>
Verification metadata is currently **read-only** in content-as-code workflows. Running `lightdash download` includes verification status in the YAML, but `lightdash upload` does not write verification back. To apply or remove the verified badge, use the three-dot menu on a chart or dashboard in the Lightdash UI.
### Two fields: `verification` and `verified`

Full CLI support for writing verification status is being tracked in [this issue](https://github.com/lightdash/lightdash/issues/22138).
</Note>
Verified content has two related fields in the YAML:

Even though verification is read-only in the CLI today, you can still build on top of verified content. Anything marked as verified in the UI is visible in the downloaded YAML, so your trusted repository can reference those charts and dashboards as the source of truth for downstream work. This is especially useful when you're using an AI agent, the [Lightdash CLI](/references/lightdash-cli), or [agent skills](/guides/developer/agent-skills) to build on top of trusted content.
- **`verification`** — read-only audit metadata showing who verified the content and when. Emitted on download for visibility in version control. Ignored on upload.
- **`verified`** — a boolean that controls verification state on upload. This is the field you edit to change verification.

Here's what a verified chart looks like after `lightdash download`:

```yaml
name: Total orders
slug: total-orders
description: Count of all orders
# ... other chart fields ...
verification:
verifiedAt: "2026-04-22T17:48:43.394Z"
verifiedBy:
firstName: David
lastName: Attenborough
userUuid: b264d83a-9000-426a-85ec-3f9c20f368ce
verified: true
```

### How `verified` behaves on upload

The `verified` field has three states:

| Value | Behavior on upload |
|---|---|
| `verified: true` | Verifies the content. No-op if already verified. |
| `verified: false` | Unverifies the content. No-op if already unverified. |
| `verified` absent | Leaves verification state unchanged. |

The "absent = leave alone" semantic means that downloading and re-uploading a YAML file you haven't touched will not unintentionally change verification state, even if you delete the `verified` line.

### Permissions

Only users with permission to verify content (organization admins and project admins) can change verification state via the CLI. If you upload a YAML containing `verified: true` or `verified: false` but you don't have verify permissions, the upload still succeeds — the rest of your changes go through, but the verification field is silently skipped and a warning is logged on the server.

This means CI pipelines run by non-admin deployers (for example, with the `developer` role) won't fail just because a YAML file contains a `verified` field they can't act on.
Loading