perses-cue-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses CUE Schema Authoring

Perses CUE Schema编写指南

Write CUE schemas for Perses plugin data models, validation constraints, JSON examples, and Grafana migration logic.

为Perses插件编写CUE Schema，涵盖数据模型、验证约束、JSON示例以及Grafana迁移逻辑。

Operator Context

操作环境说明

This skill operates as a CUE schema author for Perses plugins. It produces validated schema files, matching JSON examples, and optional migration definitions that pass

percli plugin test-schemas

本技能以Perses插件的CUE Schema编写者身份运行。可生成经过验证的Schema文件、匹配的JSON示例，以及可通过

percli plugin test-schemas

测试的可选迁移定义。

Hardcoded Behaviors (Always Apply)

强制遵循的规则（始终适用）

Package model: All plugin CUE schemas MUST use
```
package model
```
— any other package name causes compilation failure
Closed specs: Use
```
close({...})
```
for all spec definitions — open specs allow invalid fields through validation silently
JSON example required: Every schema MUST have a corresponding JSON example file at the same directory level
Test after write: Run
```
percli plugin test-schemas
```
after creating or modifying any schema — never declare a schema complete without passing tests
CUE v0.12.0+: Require CUE v0.12.0 or later; earlier versions have incompatible syntax for Perses schemas
Migration package: Migration files MUST use
```
package migrate
```
, never
```
package model
```

包名要求：所有插件CUE Schema必须使用
```
package model
```
——任何其他包名都会导致编译失败
闭合规范：所有规范定义必须使用
```
close({...})
```
——开放规范会静默允许无效字段通过验证
必填JSON示例：每个Schema必须在同一目录层级下有对应的JSON示例文件
编写后测试：创建或修改任何Schema后必须运行
```
percli plugin test-schemas
```
——未通过测试的Schema不得宣告完成
CUE版本要求：要求使用CUE v0.12.0或更高版本；早期版本的语法与Perses Schema不兼容
迁移包名：迁移文件必须使用
```
package migrate
```
，绝不能使用
```
package model
```

Default Behaviors (ON unless disabled)

默认行为（除非禁用）

Educational mode: Explain CUE syntax and Perses-specific patterns as schemas are created
Import common types: Import
```
github.com/perses/shared/cue/common
```
for shared types (
```
#format
```
,
```
#thresholds
```
,
```
#calculation
```
) rather than redefining them
Validate incrementally: Test after each schema file is written, not only at the end

教学模式：在创建Schema时讲解CUE语法和Perses专属模式
导入通用类型：导入
```
github.com/perses/shared/cue/common
```
以使用共享类型（
```
#format
```
、
```
#thresholds
```
、
```
#calculation
```
），而非重新定义
增量验证：每编写完一个Schema文件后就进行测试，而非仅在最后测试

Optional Behaviors (OFF unless enabled)

可选行为（除非启用）

Grafana migration: Write
```
migrate/migrate.cue
```
with
```
#grafanaType
```
and
```
#mapping
```
for converting Grafana panels
Strict mode: Treat all fields as required unless the user explicitly marks them optional

Grafana迁移：编写
```
migrate/migrate.cue
```
，通过
```
#grafanaType
```
和
```
#mapping
```
实现Grafana面板的转换
严格模式：所有字段均视为必填，除非用户明确标记为可选

What This Skill CAN Do

本技能可实现的功能

Define CUE schemas for any Perses plugin type (panel, variable, datasource)
Create matching JSON example files that validate against schemas
Write Grafana migration schemas with field mappings via
```
#panel
```
references
Explain CUE syntax:
```
close()
```
, optional fields (
```
?
```
), arrays (
```
[...#type]
```
), nested types (
```
#name
```
)
Debug CUE compilation errors and schema/example mismatches
Import and use shared Perses types from
```
common
```

为任何Perses插件类型（面板、变量、数据源）定义CUE Schema
创建与Schema匹配且可通过验证的JSON示例文件
通过
```
#panel
```
引用编写带有字段映射的Grafana迁移Schema
讲解CUE语法：
```
close()
```
、可选字段（
```
?
```
）、数组（
```
[...#type]
```
）、嵌套类型（
```
#name
```
）
调试CUE编译错误和Schema/示例不匹配问题
导入并使用Perses的共享通用类型

What This Skill CANNOT Do

本技能无法实现的功能

Create Perses dashboards or layouts (use perses-dashboard-create)
Scaffold full plugin projects with Go code (use perses-plugin-create)
Deploy or configure Perses server instances (use perses-deploy)
Write DaC pipeline CUE definitions (use perses-dac-pipeline)

创建Perses仪表板或布局（请使用perses-dashboard-create）
生成包含Go代码的完整插件项目脚手架（请使用perses-plugin-create）
部署或配置Perses服务器实例（请使用perses-deploy）
编写DaC流水线的CUE定义（请使用perses-dac-pipeline）

Error Handling

错误处理

CUE Compilation Error: Wrong Package Name

CUE编译错误：包名错误

Symptom:

package is "foo", want "model"

or similar CUE loader error. Cause: Schema file uses a package name other than

model

. Fix: Change the first line of the

.cue

file to

package model

. Migration files use

package migrate

instead.

症状：

package is "foo", want "model"

或类似的CUE加载器错误。原因：Schema文件使用了

model

以外的包名。修复：将

.cue

文件的第一行改为

package model

。迁移文件则需使用

package migrate

。

CUE Compilation Error: Unclosed Spec or Bad Import

CUE编译错误：未闭合规范或导入错误

Symptom:

cannot find package

expected '}' found EOF

, or

import path not valid

. Cause: Missing closing brace in

close({...})

, typo in import path, or missing import statement. Fix: Verify braces are balanced in the

close({})

block. Confirm the import path is exactly

github.com/perses/shared/cue/common

(not shortened or aliased incorrectly).

症状：

cannot find package

、

expected '}' found EOF

或

import path not valid

。原因：

close({...})

中缺少闭合大括号、导入路径拼写错误，或缺少导入语句。修复：验证

close({})

块中的大括号是否平衡。确认导入路径为

github.com/perses/shared/cue/common

（不得缩写或错误别名）。

JSON Example Mismatch: close() Rejects Unknown Fields

JSON示例不匹配：close()拒绝未知字段

Symptom:

percli plugin test-schemas

fails with

field not allowed

on a field present in the JSON but absent from the CUE schema. Cause:

close({})

enforces a strict field set — the JSON example contains fields the schema does not declare. Fix: Either add the missing field to the CUE spec (with

if optional) or remove it from the JSON example. Also check for type mismatches (e.g.,

string

in schema but

number

in JSON).

症状：

percli plugin test-schemas

测试失败，提示

field not allowed

，即JSON中存在Schema未声明的字段。原因：

close({})

强制使用严格字段集——JSON示例包含Schema未声明的字段。修复：要么将缺失字段添加到CUE规范中（若为可选则加

），要么从JSON示例中删除该字段。同时检查类型不匹配问题（例如Schema中为

string

但JSON中为

number

）。

Grafana Migration Schema Error

Grafana迁移Schema错误

Symptom:

#grafanaType

value not matching,

#mapping

field path references fail, or

#panel

lookups resolve to

_|_

(bottom). Cause:

#grafanaType

does not match the Grafana plugin ID exactly, or

#mapping

references a field path that does not exist on

#panel

. Fix: Verify

#grafanaType

matches the Grafana plugin

type

field exactly (e.g.,

"timeseries"

, not

"time_series"

). Check that

#mapping

field paths use

#panel.<field>

with the correct Grafana JSON structure.

症状：

#grafanaType

值不匹配、

#mapping

字段路径引用失败，或

#panel

查找结果为

_|_

（空值）。原因：

#grafanaType

与Grafana插件ID不完全匹配，或

#mapping

引用的字段路径在

#panel

中不存在。修复：验证

#grafanaType

与Grafana插件的

type

字段完全一致（例如

"timeseries"

，而非

"time_series"

）。检查

#mapping

字段路径是否使用

#panel.<field>

且符合Grafana JSON结构。

percli plugin test-schemas Failure: Schema/Example Not Found

percli plugin test-schemas测试失败：未找到Schema/示例

Symptom:

no schema found

no example found

— test runner skips or errors on the plugin. Cause: Directory structure does not follow the expected convention, or files are misnamed. Fix: Ensure files are at

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

and

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

. Names must match exactly.

症状：

no schema found

或

no example found

——测试运行器跳过或报错。原因：目录结构不符合约定，或文件命名错误。修复：确保文件路径为

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

和

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

。文件名必须完全一致。

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Correct Approach
Open specs (no `close({})` )	Allows any field through — invalid JSON passes validation silently	Always wrap spec fields in `close({...})`
Not importing shared types	Redefining `#format` , `#thresholds` , or `#calculation` locally diverges from upstream	Import from `github.com/perses/shared/cue/common`
Schema without JSON example	`percli plugin test-schemas` has nothing to validate against; schema correctness is unverified	Always create the `.json` example alongside the `.cue` schema
Migration without real Grafana JSON	`#mapping` paths are guessed and silently wrong at runtime	Test migration schemas against an actual exported Grafana panel JSON
Using `package migrate` for schemas	CUE loader expects `package model` for plugin schemas	Reserve `package migrate` only for files in the `migrate/` subdirectory
Nested type defined outside close()	Nested `#typeName` definitions placed outside `close({})` are not validated as part of the spec	Define nested types inside the `close({})` block

反模式	失败原因	正确做法
开放规范（未使用 `close({})` ）	允许任何字段通过——无效JSON可静默通过验证	始终将规范字段包裹在 `close({...})` 中
未导入通用类型	本地重新定义 `#format` 、 `#thresholds` 或 `#calculation` 会与上游版本产生差异	从 `github.com/perses/shared/cue/common` 导入
无JSON示例的Schema	`percli plugin test-schemas` 无验证依据，Schema正确性无法保证	始终在编写 `.cue` Schema的同时创建 `.json` 示例
未基于真实Grafana JSON的迁移	`#mapping` 路径为猜测值，运行时会静默出错	使用实际导出的Grafana面板JSON测试迁移Schema
为Schema使用 `package migrate`	CUE加载器期望插件Schema使用 `package model`	仅将 `package migrate` 用于 `migrate/` 子目录下的文件
嵌套类型定义在close()外部	定义在 `close({})` 外部的嵌套 `#typeName` 不会作为规范的一部分被验证	在 `close({})` 块内部定义嵌套类型

Anti-Rationalization

错误合理化反驳

Rationalization	Reality	Required Action
"The schema looks correct"	CUE has subtle constraints — looking correct is not being correct	Run `percli plugin test-schemas`
"close() is optional for simple schemas"	Without close(), any misspelled field passes silently	Always use close() — no exceptions
"I'll add the JSON example later"	Schema without example is untested; bugs compound	Write the JSON example before moving on
"The migration mapping is straightforward"	Grafana field paths vary across plugin versions	Test against real Grafana export JSON
"Common types aren't needed for this schema"	Diverging from upstream types causes runtime incompatibility	Import common types unless genuinely unused

错误观点	实际情况	必要操作
"这个Schema看起来是正确的"	CUE存在细微约束——看起来正确不等于实际正确	必须运行 `percli plugin test-schemas`
"简单Schema不需要close()"	没有close()时，任何拼写错误的字段都会静默通过	始终使用close()——无例外
"我稍后再添加JSON示例"	无示例的Schema未经过测试，会积累bug	在继续下一步前先编写JSON示例
"迁移映射很简单，不用测试"	Grafana字段路径随插件版本变化	使用真实Grafana导出JSON进行测试
"这个Schema不需要通用类型"	与上游类型不一致会导致运行时兼容性问题	除非确实不需要，否则必须导入通用类型

FORBIDDEN Patterns

禁止使用的模式

NEVER use
```
package
```
names other than
```
model
```
(schemas) or
```
migrate
```
(migration files)
NEVER omit
```
close({})
```
around spec definitions
NEVER declare a schema complete without a passing
```
percli plugin test-schemas
```
run
NEVER hardcode values in migration
```
#mapping
```
— always reference
```
#panel
```
field paths
NEVER place migration files outside the
```
migrate/
```
subdirectory

绝对禁止使用
```
model
```
（Schema）或
```
migrate
```
（迁移文件）以外的
```
package
```
名
绝对禁止在规范定义周围省略
```
close({})
```
绝对禁止在未通过
```
percli plugin test-schemas
```
测试的情况下宣告Schema完成
绝对禁止在迁移
```
#mapping
```
中硬编码值——必须始终引用
```
#panel
```
字段路径
绝对禁止将迁移文件放在
```
migrate/
```
子目录以外的位置

Blocker Criteria

阻塞性条件

Stop and ask the user before proceeding if:

The plugin type is not one of the standard Perses plugin types (panel, variable, datasource)
The user wants to modify shared types in
```
github.com/perses/shared
```
— these are upstream
```
percli
```
is not installed or
```
percli plugin test-schemas
```
is unavailable in the environment
The target directory already contains schemas that would be overwritten

若出现以下情况，请先询问用户再继续：

插件类型不属于标准Perses插件类型（面板、变量、数据源）
用户想要修改
```
github.com/perses/shared
```
中的共享类型——这些属于上游内容
环境中未安装
```
percli
```
或无法使用
```
percli plugin test-schemas
```
命令
目标目录已存在会被覆盖的Schema

Instructions

操作步骤

Phase 1: DEFINE DATA MODEL

阶段1：定义数据模型

Goal: Create the CUE schema for the plugin spec.

Location:

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

cue

package model

import "github.com/perses/shared/cue/common"

kind: "<PluginKind>"
spec: close({
    // Required fields
    requiredField: string

    // Optional fields (note the ?)
    optionalField?: int

    // Constrained fields using shared types
    format?: common.#format
    thresholds?: common.#thresholds
    calculation?: common.#calculation

    // Arrays of typed items
    items: [...#item]

    // Nested type definitions (inside close)
    #item: {
        name: string
        value: number
    }
})

Gate: Schema file written and syntactically valid. Proceed to Phase 2.

目标：创建插件规范的CUE Schema。

路径：

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

cue

package model

import "github.com/perses/shared/cue/common"

kind: "<PluginKind>"
spec: close({
    // 必填字段
    requiredField: string

    // 可选字段（注意?）
    optionalField?: int

    // 使用通用类型的约束字段
    format?: common.#format
    thresholds?: common.#thresholds
    calculation?: common.#calculation

    // 类型化项的数组
    items: [...#item]

    // 嵌套类型定义（在close内部）
    #item: {
        name: string
        value: number
    }
})

关卡：Schema文件已编写且语法有效。进入阶段2。

Phase 2: CREATE JSON EXAMPLE

阶段2：创建JSON示例

Goal: Write a JSON example that validates against the schema.

Location:

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

The JSON must include all required fields and valid values for any constrained types. Optional fields should be included to demonstrate their usage.

Gate: JSON example file written. Proceed to Phase 3.

目标：编写可通过Schema验证的JSON示例。

路径：

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

JSON必须包含所有必填字段，以及所有约束类型的有效值。应包含可选字段以展示其用法。

关卡：JSON示例文件已编写。进入阶段3。

Phase 3: WRITE MIGRATION (optional)

阶段3：编写迁移逻辑（可选）

Goal: Define Grafana-to-Perses field mapping.

Location:

schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue

cue

package migrate

import "github.com/perses/shared/cue/migrate"

#grafanaType: "<GrafanaPluginType>"
#mapping: {
    // Map Grafana panel fields to Perses spec fields
    perses_field: #panel.grafana_field
}

Only proceed if the user requests migration support.

Gate: Migration file written. Proceed to Phase 4.

目标：定义Grafana到Perses的字段映射。

路径：

schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue

cue

package migrate

import "github.com/perses/shared/cue/migrate"

#grafanaType: "<GrafanaPluginType>"
#mapping: {
    // 将Grafana面板字段映射到Perses规范字段
    perses_field: #panel.grafana_field
}

仅当用户要求迁移支持时才进行此步骤。

关卡：迁移文件已编写。进入阶段4。

Phase 4: VALIDATE

阶段4：验证

Goal: Confirm all schemas and examples pass validation.

bash

percli plugin test-schemas

If validation fails, return to the relevant phase and fix. Do not declare completion until tests pass.

Gate:

percli plugin test-schemas

passes. Task complete.

目标：确认所有Schema和示例通过验证。

bash

percli plugin test-schemas

若验证失败，返回对应阶段修复。只有测试通过后才可宣告任务完成。

关卡：

percli plugin test-schemas

测试通过。任务完成。

References

参考资料

Perses Plugin Development Guide — official plugin documentation
CUE Language Specification — CUE syntax and semantics
Perses Shared CUE Types —
```
common.#format
```
,
```
common.#thresholds
```
, etc.
percli CLI Reference —
```
percli plugin test-schemas
```
and other commands
Grafana Panel Schema Reference — for migration
```
#grafanaType
```
values

Perses插件开发指南 — 官方插件文档
CUE语言规范 — CUE语法和语义
Perses共享CUE类型 —
```
common.#format
```
、
```
common.#thresholds
```
等
percli CLI参考文档 —
```
percli plugin test-schemas
```
及其他命令
Grafana面板Schema参考 — 用于迁移的
```
#grafanaType
```
值