| 1 | # Schema reference |
| 2 | |
| 3 | Per-field reference for JSON Schemas under |
| 4 | `integrations/schemas/`. Each schema is JSON Schema Draft 7; |
| 5 | cross-refs use `./shared.json#/$defs/...` resolved by |
| 6 | `Registry(retrieve=retrieve_from_filesystem)` |
| 7 | (`gen_integrations.py:163-169`). |
| 8 | |
| 9 | Tables below use these column conventions: |
| 10 | - **Field**: dotted path (`a.b.c[].d` for nested arrays). |
| 11 | - **Type**: JSON Schema type or `$ref` indication. |
| 12 | - **Req**: yes / no / conditional (with the condition). |
| 13 | - **Values**: enum values, regex constraints, `minItems`, |
| 14 | `minLength`. |
| 15 | - **Surface**: which output(s) the field affects (learn / |
| 16 | www / in-app / alerts / stock / README / none). |
| 17 | - **Notes**: cross-field constraints, special handling in |
| 18 | `gen_integrations.py`. |
| 19 | |
| 20 | If the schema declares a field but no template renders it, |
| 21 | "Surface: none" is recorded; the field is still validated and |
| 22 | serialized into `integrations.js` but never appears anywhere |
| 23 | visible. |
| 24 | |
| 25 | `additionalProperties: false` is NOT set on most schemas, so |
| 26 | unknown keys pass through silently. See `gotchas.md`. |
| 27 | |
| 28 | ## shared.json -- building blocks |
| 29 | |
| 30 | Referenced by every other schema for common structures. |
| 31 | |
| 32 | ### `$defs.id` |
| 33 | |
| 34 | Single string field used in many schemas as an identifier. |
| 35 | |
| 36 | | Field | Type | Req | Values | Surface | Notes | |
| 37 | |---|---|---|---|---|---| |
| 38 | | `id` | string | yes | `minLength: 1` | all | URL-safe identifier; deduplication key in `dedupe_integrations` (`gen_integrations.py:789`). | |
| 39 | |
| 40 | ### `$defs.instance` |
| 41 | |
| 42 | The "what is this thing" descriptor used by every per-integration entry. |
| 43 | |
| 44 | | Field | Type | Req | Values | Surface | Notes | |
| 45 | |---|---|---|---|---|---| |
| 46 | | `instance.name` | string | yes | -- | learn / www / in-app | Display name. Drives slug for most types. | |
| 47 | | `instance.link` | string | yes | URL | learn / www | Official upstream site. | |
| 48 | | `instance.categories` | array<string> | yes | each must match a `categories.yaml` id | learn / www / in-app | Validated; bogus removed (`gen_integrations.py:899-912`). If none survive, falls back to `categories.yaml` entries flagged `collector_default: true` (`:906-908`). | |
| 49 | | `instance.icon_filename` | string | yes | -- | learn / www / in-app | Path under `${NETDATA_REPOS_DIR}/website/themes/tailwind/static/img/` (icon repo). | |
| 50 | | `instance.variables` | object | no | values: string / int / bool / number | all rendered text | Triggers two-pass Jinja templating; see `pipeline.md`. | |
| 51 | |
| 52 | Do not use `instance.variables` or option/default text to build the |
| 53 | short catalog description. For collector-like integrations, the |
| 54 | Monitor Anything table description is extracted from the first |
| 55 | sentence of the generated overview, usually |
| 56 | `overview.data_collection.metrics_description`. See |
| 57 | `description-authoring.md` before writing or reviewing description |
| 58 | fields. |
| 59 | |
| 60 | ### `$defs.keywords` |
| 61 | |
| 62 | Search-keyword array. |
| 63 | |
| 64 | | Field | Type | Req | Values | Surface | Notes | |
| 65 | |---|---|---|---|---|---| |
| 66 | | `keywords` | array<string> | yes (in most parent schemas) | -- | learn frontmatter, in-app search | Emitted in the `<!--startmeta` block as `keywords: ['k1','k2']`. | |
| 67 | |
| 68 | ### `$defs.short_setup` |
| 69 | |
| 70 | Minimal "Setup" block. Alternative to `full_setup` for |
| 71 | notification-style integrations. |
| 72 | |
| 73 | | Field | Type | Req | Values | Surface | Notes | |
| 74 | |---|---|---|---|---|---| |
| 75 | | `short_setup.description` | string | yes (when `short_setup` used) | markdown | learn / in-app | Free-form setup text. | |
| 76 | |
| 77 | ### `$defs.full_setup` |
| 78 | |
| 79 | The standard setup block for collectors / exporters / |
| 80 | authentication / secretstore / service_discovery. |
| 81 | |
| 82 | | Field | Type | Req | Values | Surface | Notes | |
| 83 | |---|---|---|---|---|---| |
| 84 | | `full_setup.prerequisites.list[]` | array<obj> | yes | objects with `title`, `description` | learn / in-app | Rendered as h4 sections in `setup-generic.md`. | |
| 85 | | `full_setup.prerequisites.list[].title` | string | yes | -- | learn / in-app | h4 text. | |
| 86 | | `full_setup.prerequisites.list[].description` | string | yes | markdown | learn / in-app | body. | |
| 87 | | `full_setup.configuration.file.name` | string | yes | -- | learn | Stock conf filename, e.g. `go.d/postgres.conf`. | |
| 88 | | `full_setup.configuration.file.section_name` | string | no | -- | learn | netdata.conf section, e.g. `[plugin:proc]`. | |
| 89 | | `full_setup.configuration.options.description` | string | yes | markdown | learn / in-app | Intro before the options table. | |
| 90 | | `full_setup.configuration.options.folding.title` | string | yes | -- | learn (clean strips) | Folding section title. | |
| 91 | | `full_setup.configuration.options.folding.enabled` | boolean | yes | -- | learn (clean strips) | Whether the section is collapsed by default. | |
| 92 | | `full_setup.configuration.options.list[].name` | string | yes | -- | learn / in-app | Option name (e.g. `dsn`). | |
| 93 | | `full_setup.configuration.options.list[].group` | string | no | -- | learn | Adds a "Group" column when present. | |
| 94 | | `full_setup.configuration.options.list[].description` | string | yes | markdown | learn / in-app | Short description for the table cell. | |
| 95 | | `full_setup.configuration.options.list[].detailed_description` | string | no | markdown | learn (anchor) | When set, table cell becomes a link to a detailed h5 section below. | |
| 96 | | `full_setup.configuration.options.list[].default_value` | string / number / bool | yes | -- | learn / in-app | Default value as displayed in the table. | |
| 97 | | `full_setup.configuration.options.list[].required` | boolean | yes | -- | learn / in-app | Yes/No column. | |
| 98 | | `full_setup.configuration.examples.folding` | $ref `_folding` | no | -- | learn (clean strips) | Folding for the examples block. | |
| 99 | | `full_setup.configuration.examples.list[].name` | string | yes | -- | learn / in-app | Example title. | |
| 100 | | `full_setup.configuration.examples.list[].description` | string | yes | markdown | learn / in-app | Example explanation. | |
| 101 | | `full_setup.configuration.examples.list[].config` | string | yes | YAML string | learn / in-app | Rendered inside a ```` ```yaml ```` fence. | |
| 102 | | `full_setup.configuration.examples.list[].folding` | $ref `_folding_relaxed` | no | -- | learn (clean strips) | Per-example folding override. When absent, defaults to the parent `examples.folding.enabled` (`gen_integrations.py:918-922`). | |
| 103 | |
| 104 | ### `$defs.troubleshooting` |
| 105 | |
| 106 | | Field | Type | Req | Values | Surface | Notes | |
| 107 | |---|---|---|---|---|---| |
| 108 | | `troubleshooting.problems.list[].name` | string | yes | -- | learn / in-app | Rendered as h3. | |
| 109 | | `troubleshooting.problems.list[].description` | string | yes | markdown | learn / in-app | Body. | |
| 110 | |
| 111 | The `troubleshooting.md` template adds debug-mode boilerplate |
| 112 | per plugin (e.g. `python.d.plugin`, `go.d.plugin`, |
| 113 | `charts.d.plugin`); see |
| 114 | `integrations/templates/troubleshooting.md:1-86`. |
| 115 | |
| 116 | ### `$defs._folding` |
| 117 | |
| 118 | | Field | Type | Req | Values | Surface | Notes | |
| 119 | |---|---|---|---|---|---| |
| 120 | | `_folding.title` | string | yes | -- | learn (clean strips) | Section title. | |
| 121 | | `_folding.enabled` | boolean | yes | -- | learn (clean strips) | Initial collapsed/expanded state. | |
| 122 | |
| 123 | ### `$defs._folding_relaxed` |
| 124 | |
| 125 | Same as `_folding` but only `enabled` is required; `title` |
| 126 | optional. |
| 127 | |
| 128 | ## collector.json |
| 129 | |
| 130 | Top-level structure: a `plugin_name` plus a `modules:` array |
| 131 | where each module is one collector integration. |
| 132 | |
| 133 | | Field | Type | Req | Values | Surface | Notes | |
| 134 | |---|---|---|---|---|---| |
| 135 | | `plugin_name` | string | yes | -- | (cascaded into modules) | Auto-copied to each `module.meta.plugin_name` at `gen_integrations.py:381`. | |
| 136 | | `modules` | array<obj> | yes | -- | -- | One entry per integration. | |
| 137 | | `modules[].meta.plugin_name` | string | yes | -- | id / edit_link | Redundant with top-level; both must agree (no enforcement). | |
| 138 | | `modules[].meta.module_name` | string | yes | -- | id / stock conf basename | Matches stock conf section / filename. | |
| 139 | | `modules[].meta.monitored_instance` | $ref `shared.instance` | yes | -- | all | Full instance block; `name` drives slug + sidebar label. | |
| 140 | | `modules[].meta.keywords` | $ref `shared.keywords` | yes | -- | learn / in-app | | |
| 141 | | `modules[].meta.community` | boolean | no | -- | badge color | When true, badge becomes "Community" (`gen_docs_integrations.py:424`). | |
| 142 | | `modules[].meta.related_resources.integrations.list[].plugin_name` | string | yes (in entry) | -- | related-integrations panel | | |
| 143 | | `modules[].meta.related_resources.integrations.list[].module_name` | string | conditional | required if `monitored_instance_name` is set (Draft-7 `dependencies` at `collector.json:61-63`) | related-integrations | See `gotchas.md` for non-obvious dependency semantics. | |
| 144 | | `modules[].meta.related_resources.integrations.list[].monitored_instance_name` | string | no | -- | related-integrations | For cgroups multi-instance disambiguation. | |
| 145 | | `modules[].meta.info_provided_to_referring_integrations.description` | string | yes | markdown | rendered when ANOTHER collector references this one | The "what THIS collector says when referenced from another." | |
| 146 | | `modules[].overview.data_collection.metrics_description` | string | yes | markdown | learn / www / Monitor Anything first-sentence source | The "what we collect" prose. First sentence is the catalog description and must start with an active user-facing phrase such as `Monitor...`, `Collect...`, `Enrich network flows with...`, or `Annotate network flows with...`. Do not start with setup, variables, defaults, limits, or option names. | |
| 147 | | `modules[].overview.data_collection.method_description` | string | yes | markdown | learn / www | The "how we collect" prose. | |
| 148 | | `modules[].overview.supported_platforms.include` | array<string> | yes (may be empty) | platform names | learn (`overview/collector.md:12-26`) | Allow-list. | |
| 149 | | `modules[].overview.supported_platforms.exclude` | array<string> | yes (may be empty) | platform names | learn (`overview/collector.md:12-26`) | Block-list. | |
| 150 | | `modules[].overview.multi_instance` | boolean | yes | -- | learn (`overview/collector.md:28-32`) | Drives the multi-instance sentence. | |
| 151 | | `modules[].overview.additional_permissions.description` | string | yes (may be empty) | markdown | learn (`overview/collector.md:34-36`) | When non-empty, an extra paragraph. | |
| 152 | | `modules[].overview.default_behavior.auto_detection.description` | string | yes | markdown | learn (`overview/collector.md:46-58`) | | |
| 153 | | `modules[].overview.default_behavior.limits.description` | string | yes | markdown | learn (`overview/collector.md:46-58`) | | |
| 154 | | `modules[].overview.default_behavior.performance_impact.description` | string | yes | markdown | learn (`overview/collector.md:46-58`) | | |
| 155 | | `modules[].setup` | $ref `shared.full_setup` | yes | -- | learn / in-app | Rendered through `setup-generic.md` (with sample-`<lang>`-config.md per plugin). | |
| 156 | | `modules[].troubleshooting` | $ref `shared.troubleshooting` | yes | -- | learn / in-app | | |
| 157 | | `modules[].alerts[].name` | string | yes | -- | learn alerts table | | |
| 158 | | `modules[].alerts[].link` | string | yes | URL or repo-relative | learn alerts table | Deep link to the `health.d/<...>.conf` definition. | |
| 159 | | `modules[].alerts[].metric` | string | yes | metric context | learn alerts table | Must match a metric name in `metrics.scopes[].metrics[].name` (NOT enforced). | |
| 160 | | `modules[].alerts[].info` | string | yes | -- | learn alerts table | Short alert description. | |
| 161 | | `modules[].alerts[].os` | string | no | -- | learn alerts table | OS filter. | |
| 162 | | `modules[].metrics.folding` | $ref `_folding` | yes | -- | learn (clean strips) | Folding for the entire metrics section. | |
| 163 | | `modules[].metrics.description` | string | yes | markdown | learn | Intro to the metrics block. | |
| 164 | | `modules[].metrics.availability` | array<string> | yes | -- | metrics table column-set | Defines which "availability" columns the table will have. | |
| 165 | | `modules[].metrics.dynamic_context_prefixes[].prefix` | string | no | `minLength: 1` | taxonomy | Opt-in guardrail for `taxonomy.yaml` `context_prefix:` selectors. | |
| 166 | | `modules[].metrics.dynamic_context_prefixes[].reason` | string | no | `minLength: 1` | taxonomy | Required explanation for each dynamic context prefix. | |
| 167 | | `modules[].metrics.dynamic_collect_plugins[].plugin` | string | no | `minLength: 1` | taxonomy | Opt-in guardrail for `taxonomy.yaml` `collect_plugin:` selectors. | |
| 168 | | `modules[].metrics.dynamic_collect_plugins[].reason` | string | no | `minLength: 1` | taxonomy | Required explanation for each dynamic collect-plugin selector. | |
| 169 | | `modules[].metrics.scopes[].name` | string | yes | -- | learn metrics table | Special: `global` is rewritten to `<instance> instance` at `gen_integrations.py:914-916`. | |
| 170 | | `modules[].metrics.scopes[].description` | string | yes | markdown | learn metrics table | | |
| 171 | | `modules[].metrics.scopes[].labels[].name` | string | yes | -- | learn | Label name. | |
| 172 | | `modules[].metrics.scopes[].labels[].description` | string | yes | -- | learn | | |
| 173 | | `modules[].metrics.scopes[].metrics[].name` | string | yes | metric context | learn metrics table | Chart context (e.g. `postgres.connections`). | |
| 174 | | `modules[].metrics.scopes[].metrics[].availability` | array<string> | no | matches parent `metrics.availability` | metrics table | Drives column ticks (`metrics.md:32-37`). | |
| 175 | | `modules[].metrics.scopes[].metrics[].description` | string | yes | -- | metrics table | Chart title. | |
| 176 | | `modules[].metrics.scopes[].metrics[].unit` | string | yes | -- | metrics table | | |
| 177 | | `modules[].metrics.scopes[].metrics[].chart_type` | string | yes | enum: `line, area, stacked, heatmap` | metrics table | | |
| 178 | | `modules[].metrics.scopes[].metrics[].dimensions[].name` | string | yes | -- | metrics table | | |
| 179 | | `modules[].functions.description` | string | yes (when `functions` present) | markdown | learn Live Data section | Intro. | |
| 180 | | `modules[].functions.list[].id` | string | yes | -- | learn | Function id (matches the agent's Function name). | |
| 181 | | `modules[].functions.list[].name` | string | yes | -- | learn | Display name. | |
| 182 | | `modules[].functions.list[].description` | string | yes | markdown | learn | | |
| 183 | | `modules[].functions.list[].parameters[].id` | string | yes | -- | learn parameters table | | |
| 184 | | `modules[].functions.list[].parameters[].name` | string | yes | -- | learn parameters table | | |
| 185 | | `modules[].functions.list[].parameters[].description` | string | yes | -- | learn parameters table | | |
| 186 | | `modules[].functions.list[].parameters[].type` | string | yes | -- | learn parameters table | | |
| 187 | | `modules[].functions.list[].parameters[].required` | boolean | yes | -- | learn parameters table | | |
| 188 | | `modules[].functions.list[].parameters[].default` | string / number / bool | yes | -- | learn parameters table | | |
| 189 | | `modules[].functions.list[].parameters[].options[].id` | string | yes | -- | learn parameters table | When present, parameter is enum-style. | |
| 190 | | `modules[].functions.list[].parameters[].options[].name` | string | yes | -- | learn | | |
| 191 | | `modules[].functions.list[].parameters[].options[].description` | string | no | -- | learn | | |
| 192 | | `modules[].functions.list[].parameters[].options[].default` | boolean | no | -- | learn | | |
| 193 | | `modules[].functions.list[].returns.description` | string | yes | markdown | learn | | |
| 194 | | `modules[].functions.list[].returns.columns[].name` | string | yes | -- | learn returns table | | |
| 195 | | `modules[].functions.list[].returns.columns[].type` | string | yes | -- | learn returns table | | |
| 196 | | `modules[].functions.list[].returns.columns[].unit` | string | yes | -- | learn returns table | | |
| 197 | | `modules[].functions.list[].returns.columns[].visibility` | string | no | enum: `hidden` | learn returns table | When `hidden`, column is suppressed. | |
| 198 | | `modules[].functions.list[].performance` | string | yes | markdown | learn | Performance characteristics. | |
| 199 | | `modules[].functions.list[].security` | string | yes | markdown | learn | Security considerations. | |
| 200 | | `modules[].functions.list[].availability` | string | yes | markdown | learn | When the function is available. | |
| 201 | | `modules[].functions.list[].prerequisites.list[].title` | string | yes (if prereqs present) | -- | learn | h4 text. | |
| 202 | | `modules[].functions.list[].prerequisites.list[].description` | string | yes (if prereqs present) | markdown | learn | | |
| 203 | | `modules[].functions.list[].require_cloud` | boolean | no | -- | learn functions table | Yes/No column. | |
| 204 | |
| 205 | Required at module root: `meta`, `overview`, `setup`, |
| 206 | `troubleshooting`, `alerts`, `metrics` |
| 207 | (`collector.json:611-618`). |
| 208 | |
| 209 | Required on `meta`: `plugin_name`, `module_name`, |
| 210 | `monitored_instance`, `keywords`, `related_resources`, |
| 211 | `info_provided_to_referring_integrations` (`collector.json:94-101`). |
| 212 | |
| 213 | ## taxonomy_collector.json |
| 214 | |
| 215 | Sibling authoring file for collector dashboard placement: |
| 216 | `<collector>/taxonomy.yaml`. The schema is intentionally closed |
| 217 | (`additionalProperties: false` plus `x_*` extension keys on core |
| 218 | nodes). `section_id:` is the only accepted section reference in v1; |
| 219 | `section_path:` is rejected. |
| 220 | |
| 221 | | Field | Type | Req | Values | Surface | Notes | |
| 222 | |---|---|---|---|---|---| |
| 223 | | `taxonomy_version` | integer | yes | `1` | taxonomy | Authoring schema version. | |
| 224 | | `plugin_name` | string | yes | -- | taxonomy | Must match owning `metadata.yaml`. | |
| 225 | | `module_name` | string | yes | -- | taxonomy | Must match owning `metadata.yaml` module. | |
| 226 | | `taxonomy_optout.reason` | string | conditional | `minLength: 1` | taxonomy | Mutually exclusive with `placements`. | |
| 227 | | `inline_dynamic_declarations.dynamic_context_prefixes[]` | array<object> | no | `prefix`, `reason` | taxonomy | For no-metadata plugins only. Fails when sibling metadata exists. | |
| 228 | | `inline_dynamic_declarations.dynamic_collect_plugins[]` | array<object> | no | `plugin`, `reason` | taxonomy | For no-metadata plugins only. | |
| 229 | | `placements[].id` | string | yes | `^[a-z0-9][a-z0-9_.-]*$` | taxonomy | Leaf id under the target section. | |
| 230 | | `placements[].section_id` | string | yes | registered section id | taxonomy | Resolved against `integrations/taxonomy/sections.yaml`. | |
| 231 | | `placements[].title` | string | yes | -- | taxonomy | Multi-node canonical title. | |
| 232 | | `placements[].icon` | string | no | registered icon id | taxonomy | Resolved against `integrations/taxonomy/icons.yaml`. | |
| 233 | | `placements[].families` | boolean / array<string> | no | -- | taxonomy | Preserved for the dashboard TOC consumer. | |
| 234 | | `placements[].items[]` | array | yes | recursive item tree | taxonomy | Ordered TOC tree; strings in structural positions own contexts. | |
| 235 | | `items[].type` | string | conditional | `owned_context`, `group`, `flatten`, `selector`, `context`, `grid`, `first_available`, `view_switch` | taxonomy | Plain strings normalize to `owned_context`. | |
| 236 | | `owned_context.context` | string | yes | real context | taxonomy | Must exist in metadata. | |
| 237 | | `selector.context_prefix[]` | array<string> | conditional | unique | taxonomy | Dynamic selector; requires metadata opt-in. May narrow a declared metadata namespace, e.g. `snmp.device_prof_` under declared `snmp.`. | |
| 238 | | `selector.context_prefix_exclude[]` | array<string> | no | unique | taxonomy | Valid only with same-node `context_prefix`. | |
| 239 | | `selector.collect_plugin[]` | array<string> | conditional | unique | taxonomy | Dynamic selector by `_collect_plugin`; requires metadata opt-in. | |
| 240 | | `context.contexts[]` | array | yes | literal context, unresolved object, or selector object | taxonomy | Widget references; literal references must resolve or carry `unresolved`. | |
| 241 | | `context.chart_library` | string | yes | `bars`, `d3pie`, `dygraph`, `easypiechart`, `gauge`, `groupBoxes`, `number`, `table` | taxonomy | Display widget renderer. | |
| 242 | | `context.group_by[]` | array<string> | no | unique | taxonomy | Widget grouping axes, e.g. `selected`, `dimension`, `label`, `node`, `context`. | |
| 243 | | `context.group_by_label[]` | array<string> | no | unique | taxonomy | Label names used when `group_by` includes `label`. | |
| 244 | | `context.aggregation_method` | string | no | `avg`, `max`, `min`, `sum` | taxonomy | Aggregation method for grouped widgets. | |
| 245 | | `context.selected_dimensions[]` | array<string> | no | unique | taxonomy | Explicit dimensions to show in the widget. | |
| 246 | | `context.dimensions_sort` | string | no | non-empty | taxonomy | FE dimension sort directive, e.g. `valueDesc`. | |
| 247 | | `context.colors[]` | array<string> | no | non-empty strings | taxonomy | Renderer color palette values. | |
| 248 | | `context.layout` | object | no | `left`, `top`, `width`, `height` | taxonomy | Grid coordinates for `grid.items` widgets. | |
| 249 | | `context.table_columns[]` | array<string> | no | unique | taxonomy | Table widget column axes, e.g. `context`, `dimension`. | |
| 250 | | `context.table_sort_by[]` | array<object> | no | `{id, desc}` | taxonomy | Table sort directives. | |
| 251 | | `context.labels` | object | no | string map | taxonomy | Context or dimension display labels. | |
| 252 | | `context.value_range[]` | array<number|null> | no | at least one item | taxonomy | Numeric renderer bounds, usually `[0, null]` or `[0, 100]`. | |
| 253 | | `context.eliminate_zero_dimensions` | boolean | no | -- | taxonomy | Renderer hint to hide all-zero dimensions. | |
| 254 | | `context.context_items[]` | array<object> | no | `{value, label}` | taxonomy | Per-widget context item labels for selector-like UI. | |
| 255 | | `context.post_group_by[]` | array<string> | no | unique | taxonomy | Post-aggregation grouping axes. | |
| 256 | | `context.show_post_aggregations` | boolean | no | -- | taxonomy | FE post-aggregation display toggle. | |
| 257 | | `context.grouping_method` | string | no | non-empty | taxonomy | FE grouping-method override. | |
| 258 | | `context.sparkline` | boolean | no | -- | taxonomy | Render compact sparkline form when supported. | |
| 259 | | `renderer` | object | no | `overlays`, `url_options`, `toolbox_elements`, `x_*` | taxonomy | Renderer-private payload envelope. | |
| 260 | | `placements[].single_node` | object | no | closed field set | taxonomy | Sparse override block; top-level fields are multi-node defaults. | |
| 261 | |
| 262 | Item-kind matrix: |
| 263 | |
| 264 | | Item kind | Required fields | Allowed children / references | Notes | |
| 265 | |---|---|---|---| |
| 266 | | string shorthand | string value | none | Structural positions only; normalizes to `owned_context`. | |
| 267 | | `owned_context` | `type`, `context` | none | Owns one literal context. | |
| 268 | | `group` | `type`, `id`, `title`, `items` | structural `items` | `id` is stable across title renames. | |
| 269 | | `flatten` | `type`, `id`, `title`, `items` | non-flatten structural `items` | Equivalent to legacy `justGroup`; nested flatten is invalid. | |
| 270 | | `selector` | `type`, `id`, `title`, one of `context_prefix` or `collect_plugin` | none | Owns the resolved selector snapshot. | |
| 271 | | `context` | `type`, `contexts`, `chart_library` | widget `contexts` references | References contexts but does not own them. | |
| 272 | | `grid` | `type`, `id`, `items` | `context`, `first_available`, display `view_switch` | Grid children are display-only. | |
| 273 | | `first_available` | `type`, `items` | `context`, `grid`, display `view_switch` | Alternatives are ordered and display-only. | |
| 274 | | `view_switch` | `type`, `multi_node`, `single_node` | concrete object branches except `flatten` or nested `view_switch` | Branches are whole-body replacements; no string branches. | |
| 275 | |
| 276 | For a rich collector example with grids, table widgets, nested groups, |
| 277 | and ownership leaves, read |
| 278 | `src/go/plugin/go.d/collector/mysql/taxonomy.yaml`. |
| 279 | |
| 280 | Widget `contexts[]` entries may be: |
| 281 | |
| 282 | - a literal context string; |
| 283 | - an unresolved literal reference object: |
| 284 | `{context, unresolved: {reason, owner, expires}}`, where |
| 285 | `expires` is `YYYY-MM-DD`; |
| 286 | - a selector reference object with `context_prefix` or |
| 287 | `collect_plugin`. |
| 288 | |
| 289 | Generated output adds `unresolved_references[]` to each placement and |
| 290 | item that aggregates unresolved escape hatches with `context`, |
| 291 | `reason`, `owner`, `expires`, and `item_path`. |
| 292 | |
| 293 | ## taxonomy_sections.json |
| 294 | |
| 295 | Schema for `integrations/taxonomy/sections.yaml`. Sections have |
| 296 | stable opaque `id` values and parentage through `parent_id`. |
| 297 | Moving a section means changing `parent_id`, not editing collector |
| 298 | `taxonomy.yaml` files. |
| 299 | |
| 300 | Required fields per section: `id`, `title`, `section_order`, |
| 301 | `status`. Optional fields: `parent_id`, `short_name`, `icon`, |
| 302 | `deprecation`, and `x_*` extensions. |
| 303 | |
| 304 | ## taxonomy_output.json |
| 305 | |
| 306 | Schema for generated `integrations/taxonomy.json`. The artifact |
| 307 | contains `taxonomy_schema_version`, `source`, normalized `sections`, |
| 308 | normalized `placements`, and `opted_out_collectors`. Each placement |
| 309 | preserves the ordered item tree and includes `resolved_contexts` |
| 310 | (owned contexts), `referenced_contexts` (display references), and |
| 311 | `unresolved_references` snapshots for CI/review diffing. |
| 312 | |
| 313 | ## agent_notification.json |
| 314 | |
| 315 | Single object OR array of objects (oneOf). |
| 316 | |
| 317 | | Field | Type | Req | Values | Surface | Notes | |
| 318 | |---|---|---|---|---|---| |
| 319 | | `id` | $ref `shared.id` | yes | -- | id / dedupe | | |
| 320 | | `meta` | $ref `shared.instance` | yes | -- | learn / in-app | `meta.name` drives slug. | |
| 321 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 322 | | `overview.notification_description` | string | yes | markdown | learn (`overview/notification.md`) | The "what gets notified" prose. | |
| 323 | | `overview.notification_limitations` | string | yes (may be empty) | markdown | learn | When non-empty, rendered as `## Limitations`. | |
| 324 | | `global_setup.severity_filtering` | boolean | yes | -- | learn | Sentence in setup template. | |
| 325 | | `global_setup.http_proxy` | boolean | yes | -- | learn | Sentence in setup template. | |
| 326 | | `setup` | oneOf [`shared.short_setup`, `shared.full_setup`] | yes | -- | learn / in-app | Rendered by `setup-generic.md` which handles both shapes. | |
| 327 | | `troubleshooting` | $ref `shared.troubleshooting` | no | -- | learn / in-app | | |
| 328 | |
| 329 | ## cloud_notification.json |
| 330 | |
| 331 | Same shape as `agent_notification.json` minus `overview` |
| 332 | (none required), with `setup` required. |
| 333 | |
| 334 | | Field | Type | Req | Values | Surface | Notes | |
| 335 | |---|---|---|---|---|---| |
| 336 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 337 | | `meta` | $ref `shared.instance` | yes | -- | learn / in-app | | |
| 338 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 339 | | `setup` | oneOf [`shared.short_setup`, `shared.full_setup`] | yes | -- | learn / in-app | | |
| 340 | | `troubleshooting` | $ref `shared.troubleshooting` | no | -- | learn / in-app | | |
| 341 | |
| 342 | `integrations/cloud-notifications/metadata.yaml` is a single |
| 343 | file containing an ARRAY of these entries (one per |
| 344 | notification destination). |
| 345 | |
| 346 | ## authentication.json |
| 347 | |
| 348 | Same shape as `agent_notification.json` with renamed `overview` |
| 349 | fields for the authentication context. |
| 350 | |
| 351 | | Field | Type | Req | Values | Surface | Notes | |
| 352 | |---|---|---|---|---|---| |
| 353 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 354 | | `meta` | $ref `shared.instance` | yes | -- | learn / in-app | | |
| 355 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 356 | | `overview.authentication_description` | string | yes | markdown | learn (`overview/authentication.md`) | | |
| 357 | | `overview.authentication_limitations` | string | yes (may be empty) | markdown | learn | | |
| 358 | | `setup` | oneOf [`shared.short_setup`, `shared.full_setup`] | yes | -- | learn / in-app | | |
| 359 | | `troubleshooting` | $ref `shared.troubleshooting` | no | -- | learn / in-app | | |
| 360 | |
| 361 | `integrations/cloud-authentication/metadata.yaml` is a single |
| 362 | file with an array of authentication-method entries. |
| 363 | |
| 364 | ## logs.json |
| 365 | |
| 366 | Single entry OR array. Required: `id`, `meta`, `keywords`, |
| 367 | `overview`. |
| 368 | |
| 369 | | Field | Type | Req | Values | Surface | Notes | |
| 370 | |---|---|---|---|---|---| |
| 371 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 372 | | `meta` | $ref `shared.instance` | yes | -- | learn / in-app | | |
| 373 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 374 | | `overview.description` | string | yes | markdown | learn (`overview/logs.md`) | h1 body. | |
| 375 | | `overview.visualization.description` | string | yes | markdown | learn | `## Visualization` section. | |
| 376 | | `overview.key_features.description` | string | yes | markdown | learn | `## Key features` section. | |
| 377 | | `setup.prerequisites.description` | string | yes (when `setup` present) | markdown | learn (`setup-logs.md`) | | |
| 378 | |
| 379 | `integrations/logs/metadata.yaml` covers exactly three log |
| 380 | types: `systemd-journal`, `windows-events`, `OpenTelemetry`. |
| 381 | |
| 382 | ## secretstore.json |
| 383 | |
| 384 | Per-backend entries. |
| 385 | |
| 386 | | Field | Type | Req | Values | Surface | Notes | |
| 387 | |---|---|---|---|---|---| |
| 388 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 389 | | `meta.kind` | string | yes | -- | slug | **Drives slug** (NOT `meta.name`); matches stock conf filename `/etc/netdata/go.d/ss/<kind>.conf`. | |
| 390 | | `meta.name` | string | yes | -- | learn / in-app | Display name. | |
| 391 | | `meta.link` | string | yes | URL | learn / www | | |
| 392 | | `meta.icon_filename` | string | yes | -- | learn / www / in-app | | |
| 393 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 394 | | `overview.description` | string | yes | markdown | learn (`overview/secretstore.md`) | | |
| 395 | | `overview.limitations` | string | no | markdown | learn | | |
| 396 | | `setup` | $ref `shared.full_setup` | yes | -- | learn / in-app | Rendered via `setup-secretstore.md`. | |
| 397 | | `collector_configs.description` | string | yes | markdown | learn (`collector_configs.md`) | | |
| 398 | | `collector_configs.summary.operand_format` | string | yes | -- | `SECRETS.md` umbrella table | Used by `gen_doc_secrets_page.py` to build the supported-backends table. | |
| 399 | | `collector_configs.summary.example_operand` | string | yes | -- | `SECRETS.md` umbrella table | as above | |
| 400 | | `collector_configs.format.description` | string | no | markdown | learn | | |
| 401 | | `collector_configs.format.syntax` | string | yes | -- | learn | E.g. `${store:<kind>:<name>:<operand>}`. | |
| 402 | | `collector_configs.format.parts.list[].name` | string | yes | -- | learn | | |
| 403 | | `collector_configs.format.parts.list[].description` | string | yes | -- | learn | | |
| 404 | | `collector_configs.examples.list[].name` | string | yes (`minItems: 1`) | -- | learn | | |
| 405 | | `collector_configs.examples.list[].description` | string | yes | -- | learn | | |
| 406 | | `collector_configs.examples.list[].content` | string | yes | -- | learn | Code block. | |
| 407 | | `collector_configs.examples.list[].language` | string | no | language id | learn | Code-fence language; defaults to `text` per schema description but template uses `'yaml'`. | |
| 408 | | `troubleshooting` | $ref `shared.troubleshooting` | yes | -- | learn / in-app | | |
| 409 | |
| 410 | ## service_discovery.json |
| 411 | |
| 412 | | Field | Type | Req | Values | Surface | Notes | |
| 413 | |---|---|---|---|---|---| |
| 414 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 415 | | `meta.kind` | string | yes | -- | slug | **Drives slug**; matches discoverer registry name and stock conf filename. | |
| 416 | | `meta.name` | string | yes | -- | learn / in-app | | |
| 417 | | `meta.tagline` | string | yes | -- | SD hub table | One-liner shown in the SERVICE-DISCOVERY.md table. | |
| 418 | | `meta.link` | string | yes | URL | learn / www | | |
| 419 | | `meta.icon_filename` | string | yes | -- | learn / www / in-app | | |
| 420 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 421 | | `overview.description` | string | yes | markdown | learn (`overview/service_discovery.md`) | | |
| 422 | | `overview.how_it_works` | string | no | markdown | learn | h3 under Overview. | |
| 423 | | `overview.limitations` | string | no | markdown | learn | | |
| 424 | | `setup` | $ref `shared.full_setup` | yes | -- | learn (`setup-service_discovery.md`) | | |
| 425 | | `services.description` | string | yes | markdown | learn | | |
| 426 | | `services.evaluation.description` | string | no | markdown | learn | | |
| 427 | | `services.evaluation.list[].name` | string | yes | -- | learn | Evaluation criterion. | |
| 428 | | `services.evaluation.list[].description` | string | yes | -- | learn | | |
| 429 | | `services.template_variables.description` | string | no | markdown | learn | | |
| 430 | | `services.template_variables.list[].name` | string | yes (`minItems: 1`) | -- | learn | Discoverer-specific template var name. | |
| 431 | | `services.template_variables.list[].description` | string | yes | -- | learn | | |
| 432 | | `services.template_variables.list[].type` | string | no | -- | learn | | |
| 433 | | `services.examples.description` | string | no | markdown | learn | | |
| 434 | | `services.examples.list[].name` | string | yes (`minItems: 1`) | -- | learn | | |
| 435 | | `services.examples.list[].description` | string | yes | -- | learn | | |
| 436 | | `services.examples.list[].config` | string | yes | -- | learn | YAML code block. | |
| 437 | | `verify.description` | string | no | markdown | learn | | |
| 438 | | `verify.checks.list[].name` | string | yes (`minItems: 1` when `verify` present) | -- | learn | | |
| 439 | | `verify.checks.list[].description` | string | yes | -- | learn | | |
| 440 | | `troubleshooting` | $ref `shared.troubleshooting` | yes | -- | learn / in-app | | |
| 441 | |
| 442 | Required at entry root: `id`, `meta`, `keywords`, `overview`, |
| 443 | `setup`, `services`, `troubleshooting` (`service_discovery.json:237-245`). |
| 444 | |
| 445 | ## deploy.json |
| 446 | |
| 447 | Top-level: ARRAY of objects (one per deploy method). |
| 448 | |
| 449 | | Field | Type | Req | Values | Surface | Notes | |
| 450 | |---|---|---|---|---|---| |
| 451 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 452 | | `meta` | $ref `shared.instance` | yes | -- | in-app dialog | `meta.categories` must include a `deploy.*` id. | |
| 453 | | `keywords` | array<string> | yes | -- | in-app search | | |
| 454 | | `install_description` | string | yes | markdown | in-app dialog | | |
| 455 | | `methods[].method` | string | yes | -- | in-app dialog | E.g. `wget`, `curl`, `kubectl`. | |
| 456 | | `methods[].commands[].channel` | string (enum) | yes | enum: `nightly`, `stable` | in-app dialog | | |
| 457 | | `methods[].commands[].command` | string | yes | -- | in-app dialog | May contain custom tags `{% if $showClaimingOptions %}...{% /if %}`; stripped when `clean=True` (`gen_integrations.py:982-985`). | |
| 458 | | `additional_info` | string | yes | markdown | in-app dialog | May contain custom tags. | |
| 459 | | `clean_additional_info` | string | no | markdown | in-app dialog | Clean-variant override; when present, replaces `additional_info` in the `clean_*` branch (`gen_integrations.py:990-992`). | |
| 460 | | `related_resources` | object | yes | -- | (TBD/empty) | Currently unused. | |
| 461 | | `platform_info.group` | string (enum) | yes | enum: `include`, `no_include`, `""` | in-app dialog | `include`/`no_include` cross-ref `distros.yml` to filter the platform table. | |
| 462 | | `platform_info.distro` | string | yes | -- | in-app dialog | Matches `distros.yml` `distro` field. | |
| 463 | | `quick_start` | integer | yes | -- | in-app "Add Nodes" dialog | Sort order. Negative -> hidden. | |
| 464 | |
| 465 | Custom tag patterns recognized in `command` / `additional_info`: |
| 466 | `{% if X %}...{% /if %}`, `{%...%}` (regex |
| 467 | `gen_integrations.py:124`). Stripped when generating |
| 468 | `clean=True` outputs. |
| 469 | |
| 470 | ## exporter.json |
| 471 | |
| 472 | Same pattern as `agent_notification.json` with |
| 473 | `overview.exporter_description` and |
| 474 | `overview.exporter_limitations`. |
| 475 | |
| 476 | | Field | Type | Req | Values | Surface | Notes | |
| 477 | |---|---|---|---|---|---| |
| 478 | | `id` | $ref `shared.id` | yes | -- | id | | |
| 479 | | `meta` | $ref `shared.instance` | yes | -- | learn / in-app | | |
| 480 | | `keywords` | array<string> | yes | -- | learn frontmatter | | |
| 481 | | `overview.exporter_description` | string | yes | markdown | learn (`overview/exporter.md`) | | |
| 482 | | `overview.exporter_limitations` | string | yes (may be empty) | markdown | learn | When non-empty, rendered as `## Limitations`. | |
| 483 | | `setup` | $ref `shared.full_setup` | yes | -- | learn / in-app | | |
| 484 | | `troubleshooting` | $ref `shared.troubleshooting` | yes | -- | learn / in-app | | |
| 485 | |
| 486 | ## categories.json |
| 487 | |
| 488 | Recursive tree definition. |
| 489 | |
| 490 | | Field | Type | Req | Values | Surface | Notes | |
| 491 | |---|---|---|---|---|---| |
| 492 | | `id` | string | yes | -- | category lookup | Dotted path, e.g. `data-collection.databases`. | |
| 493 | | `name` | string | yes | -- | navigation | Display name. | |
| 494 | | `description` | string | yes | markdown | navigation | Tooltip / overview. | |
| 495 | | `children` | array<obj> | yes (may be empty) | -- | navigation | Recursive structure. | |
| 496 | | `collector_default` | boolean | no | -- | fallback | When true, this category is the default if a collector's declared categories are all bogus (`gen_integrations.py:906-908`). | |
| 497 | |
| 498 | ## distros.json |
| 499 | |
| 500 | Validates `.github/data/distros.yml`. **NOT actually |
| 501 | enforced** -- `gen_integrations.py:1330` calls `load_yaml` |
| 502 | without passing this schema. See `gotchas.md`. |
| 503 | |
| 504 | Top-level keys: `platform_map` (CPU arch -> docker platform |
| 505 | string), `arch_order`, `include[]` (array of platform |
| 506 | descriptors). |
| 507 | |
| 508 | Per-platform descriptor fields: |
| 509 | |
| 510 | | Field | Type | Req | Values | Surface | Notes | |
| 511 | |---|---|---|---|---|---| |
| 512 | | `distro` | string | yes | regex `^[a-z][a-z0-9]*$` | deploy platform table | | |
| 513 | | `version` | string | yes | regex `^[a-z0-9][a-z.0-9]*$` | deploy platform table | | |
| 514 | | `support_type` | string | yes | enum: `Core`, `Intermediate`, `Community`, `Third-Party`, `Unsupported` | deploy platform table | | |
| 515 | | `notes` | string | yes | -- | deploy platform table | | |
| 516 | | `eol_check` | bool / string | no | -- | deploy build matrix | | |
| 517 | | `bundle_sentry` | bool / string | yes | -- | deploy build matrix | | |
| 518 | | `base_image` | string | no | -- | deploy build matrix | | |
| 519 | | `env_prep` | string | no | -- | deploy build matrix | | |
| 520 | | `jsonc_removal` | string | no | -- | deploy build matrix | | |
| 521 | | `test.ebpf-core` | bool | no | -- | deploy build matrix | | |
| 522 | | `packages.type` | string | no | -- | deploy build matrix | | |
| 523 | | `packages.arches` | array<string> | no | -- | deploy build matrix | | |
| 524 | | `packages.repo_distro` | string | no | -- | deploy build matrix | | |
| 525 | | `packages.alt_links` | array | no | -- | deploy build matrix | | |
| 526 | |
| 527 | Required: `distro`, `version`, `support_type`, `notes`, |
| 528 | `bundle_sentry`. Garbage in `distros.yml` produces broken |
| 529 | `platform_info` tables silently. |
| 530 | |
| 531 | ## Cross-schema notes |
| 532 | |
| 533 | - The `<plugin-dir>/metadata.yaml` for collectors uses one of |
| 534 | two top-level shapes (`gen_integrations.py:381`): |
| 535 | - **Single-module** -- `plugin_name` and `modules: [<one>]`. |
| 536 | - **Multi-module** -- `plugin_name` and `modules: [<many>]`. |
| 537 | Both are validated against the same `collector.json` schema. |
| 538 | The split single/multi validation in |
| 539 | `check_collector_metadata.py` is dead code (see `gotchas.md`). |
| 540 | |
| 541 | - Schema `shared.json` cross-refs are resolved by |
| 542 | `Registry(retrieve=retrieve_from_filesystem)` so changes to |
| 543 | `shared.json` propagate to all consumers immediately. |
| 544 | |
| 545 | - `additionalProperties: false` is NOT set on most schemas. |
| 546 | Unknown keys (`alternative_monitored_instances`, |
| 547 | `most_popular`) pass through silently into `integrations.js` |
| 548 | but no template renders them. See `gotchas.md`. |
| 549 | |
| 550 | - Validation warnings are FATAL: `fail_on_warnings()` |
| 551 | (`gen_integrations.py:150-160`) returns 1 on any warning, |
| 552 | causing CI to fail and aborting doc regeneration. |