Skip to content

[FEATURE] Add panel-level annotations to the data model - #61

Merged
nicolastakashi merged 1 commit into
perses:mainfrom
nicolastakashi:draft/panel-level-annotations-model
Jul 31, 2026
Merged

[FEATURE] Add panel-level annotations to the data model#61
nicolastakashi merged 1 commit into
perses:mainfrom
nicolastakashi:draft/panel-level-annotations-model

Conversation

@nicolastakashi

@nicolastakashi nicolastakashi commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What this does

This adds an optional annotations block to PanelSpec so annotations can be set per panel. It follows the two-level annotation design being discussed in perses/perses#3001. The dashboard-level half of that design already shipped, and this PR is the data model for the panel-level half.

type PanelAnnotations struct {
    // Enabled toggles the display of dashboard-level annotations on this panel.
    // nil is treated as enabled (default on).
    Enabled     *bool
    // Definitions holds annotations defined locally on this panel, reusing AnnotationSpec.
    Definitions []AnnotationSpec
}

Enabled is a pointer so an omitted value means "on", which is the default-on behavior from the design. Definitions reuses the existing AnnotationSpec type instead of a new parallel shape.

Scope

This is the data model only. It does not touch backend validation, the frontend consumer hook, the panel editor, or Grafana migration, which I will send as separate follow-ups to keep this one small. I opened it as a draft because the shape is still under discussion on #3001, and I would rather agree on that before building the layers on top of it.

Mirrors

The Go types are the source of truth. I regenerated the CUE mirror with make cue-gen (not hand-edited) and updated the TypeScript (ts/src/dashboard/panel.ts) and Java (.../dashboard/panel/PanelSpec.java plus a new PanelAnnotations.java) mirrors by hand.

Validation

Panel-local definitions get validated without any extra code. AnnotationSpec.UnmarshalJSON already calls validate(), which requires a non-empty name, and that runs when a definition is unmarshaled inside a PanelSpec. So I did not add validation to PanelSpec itself.

Testing

go/dashboard/panel_test.go covers JSON and YAML round-trips, the default-on case when the block is omitted, and rejection of a definition with an empty name.

  • make cue-gen cue-eval: clean
  • go test ./go/...: all pass
  • gofmt -l go/: clean

This was referenced Jul 24, 2026
Open
Draft
Draft
@nicolastakashi
nicolastakashi force-pushed the draft/panel-level-annotations-model branch from 9852027 to a52f6e1 Compare July 30, 2026 10:43
@nicolastakashi
nicolastakashi marked this pull request as ready for review July 30, 2026 10:43
Gladorme
Gladorme reviewed Jul 30, 2026
View reviewed changes

@Gladorme Gladorme left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did we not say we are dropping enabled? And PanelSpec now has annotations []AnnotationSpec directly?

Comment thread cue/dashboard/dashboard_go_gen.cue Outdated
// Enabled toggles the display of dashboard-level annotations on this panel.
// A nil value is treated as enabled, matching the "on by default" behavior of the
// two-level annotation design.
enabled?: null | bool @go(Enabled,*bool)

@Gladorme Gladorme Jul 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We said we are dropping this enabled, no?
As there is "hide" in display

Comment thread go/dashboard/dashboard.go Outdated
// Enabled toggles the display of dashboard-level annotations on this panel.
// A nil value is treated as enabled, matching the "on by default" behavior of the
// two-level annotation design.
Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

@Gladorme Gladorme Jul 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here

Comment thread ts/src/dashboard/panel.ts Outdated

export interface PanelAnnotations {
// Toggles the display of dashboard-level annotations on this panel. Undefined is treated as enabled.
enabled?: boolean;

@Gladorme Gladorme Jul 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same

Comment thread cue/dashboard/dashboard_go_gen.cue Outdated
plugin: plugin_9.#Plugin @go(Plugin)
queries?: [...#Query] @go(Queries,[]Query)
links?: [...#Link] @go(Links,[]Link)
annotations?: null | #PanelAnnotations @go(Annotations,*PanelAnnotations)

@Gladorme Gladorme Jul 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
annotations?: null | #PanelAnnotations @go(Annotations,*PanelAnnotations)
annotations?: null | [...#AnnotationSpec] @go(Definitions,[]AnnotationSpec)

@nicolastakashi
nicolastakashi force-pushed the draft/panel-level-annotations-model branch from a52f6e1 to 038c137 Compare July 31, 2026 10:34
@nicolastakashi
[FEATURE] Add panel-level annotations to the data model
bfa1d48 
Add an optional annotations list to PanelSpec so annotations can be configured
per panel, following the two-level annotation design discussed in
perses/perses#3001. Panel-local annotations reuse the existing AnnotationSpec
type and mirror the dashboard-level Spec.Annotations shape. They apply only to
their own panel, on top of the dashboard-level annotations that apply to every
panel. Per-annotation visibility is handled by AnnotationSpec.Display.Hidden, so
no panel-level toggle is needed.

Regenerate the CUE mirror and update the TypeScript and Java mirrors to match.

Signed-off-by: Nicolas Takashi <nicolas.takashi@dash0.com>
@nicolastakashi
nicolastakashi force-pushed the draft/panel-level-annotations-model branch from 038c137 to bfa1d48 Compare July 31, 2026 10:36
Gladorme
Gladorme approved these changes Jul 31, 2026
View reviewed changes

@Gladorme Gladorme left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lgtm 😁

@nicolastakashi
nicolastakashi added this pull request to the merge queue Jul 31, 2026
Merged via the queue into perses:main with commit 19816aa Jul 31, 2026
13 checks passed
@nicolastakashi
nicolastakashi deleted the draft/panel-level-annotations-model branch July 31, 2026 15:56
nicolastakashi added a commit to nicolastakashi/perses that referenced this pull request Jul 31, 2026
@nicolastakashi
[FEATURE] Validate panel-level annotation definitions
0265dc2 
Extend ValidatePanels so that panel-local annotation definitions
(PanelSpec.Annotations.Definitions) are schema-validated through the existing
ValidateAnnotations path, exactly like dashboard-level annotations. No new
plugin kind is introduced; KindAnnotation already exists.

Add annotation schema and sample fixtures plus a TestValidatePanelsWithAnnotations
covering a valid definition, an unknown annotation kind, the toggle-only case, and
a panel with no annotations block.

Depends on the panel-level annotations data model in perses/spec#61.

Signed-off-by: Nicolas Takashi <nicolas.takashi@dash0.com>
@nicolastakashi nicolastakashi mentioned this pull request Aug 4, 2026
Merged
nicolastakashi added a commit to nicolastakashi/perses that referenced this pull request Aug 4, 2026
@nicolastakashi
[FEATURE] Validate panel-level annotation definitions
6e05ee6 
Extend ValidatePanels so that panel-local annotation definitions
(PanelSpec.Annotations.Definitions) are schema-validated through the existing
ValidateAnnotations path, exactly like dashboard-level annotations. No new
plugin kind is introduced; KindAnnotation already exists.

Add annotation schema and sample fixtures plus a TestValidatePanelsWithAnnotations
covering a valid definition, an unknown annotation kind, the toggle-only case, and
a panel with no annotations block.

Depends on the panel-level annotations data model in perses/spec#61.

Signed-off-by: Nicolas Takashi <nicolas.takashi@dash0.com>
nicolastakashi added a commit to nicolastakashi/perses that referenced this pull request Aug 4, 2026
@nicolastakashi
[FEATURE] Validate panel-level annotation definitions
fd76c2e 
Extend ValidatePanels so that panel-local annotation definitions
(PanelSpec.Annotations.Definitions) are schema-validated through the existing
ValidateAnnotations path, exactly like dashboard-level annotations. No new
plugin kind is introduced; KindAnnotation already exists.

Add annotation schema and sample fixtures plus a TestValidatePanelsWithAnnotations
covering a valid definition, an unknown annotation kind, the toggle-only case, and
a panel with no annotations block.

Depends on the panel-level annotations data model in perses/spec#61.

Signed-off-by: Nicolas Takashi <nicolas.takashi@dash0.com>
nicolastakashi added a commit to nicolastakashi/perses that referenced this pull request Aug 4, 2026
@nicolastakashi
[FEATURE] Validate panel-level annotation definitions
849dcd8 
Extend ValidatePanels so that panel-local annotation definitions
(PanelSpec.Annotations.Definitions) are schema-validated through the existing
ValidateAnnotations path, exactly like dashboard-level annotations. No new
plugin kind is introduced; KindAnnotation already exists.

Add annotation schema and sample fixtures plus a TestValidatePanelsWithAnnotations
covering a valid definition, an unknown annotation kind, the toggle-only case, and
a panel with no annotations block.

Depends on the panel-level annotations data model in perses/spec#61.

Signed-off-by: Nicolas Takashi <nicolas.takashi@dash0.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Gladorme Gladorme Gladorme approved these changes
@Nexucis Nexucis Awaiting requested review from Nexucis
@AntoineThebaud AntoineThebaud Awaiting requested review from AntoineThebaud

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nicolastakashi @Gladorme