Add exporter integration schema. (#15545)

Also splits a bit more out to shared definitions.

6 files changed, 295 insertions, 209 deletions

diff --git a/exporting/sample-metadata.yaml b/exporting/sample-metadata.yaml
new file mode 100644
index 0000000000..41a287aeb1
--- /dev/null
+++ b/exporting/sample-metadata.yaml
@@ -0,0 +1,39 @@
+id: ''
+meta:
+  name: ''
+  link: ''
+  categories: []
+  icon_filename: ''
+keywords: []
+overview:
+  exporter_description: ''
+  exporter_limitations: ''
+setup:
+  prerequisites:
+    list:
+      - title: ''
+        description: ''
+  configuration:
+    file:
+      name: ''
+      description: ''
+    options:
+      description: ''
+      folding:
+        title: ''
+        enabled: true
+      list:
+        - name: ''
+          default_value: ''
+          description: ''
+          required: false
+    examples:
+      folding:
+        enabled: true
+        title: ''
+      list:
+        - name: ''
+          folding:
+            enabled: false
+          description: ''
+          config: ''
diff --git a/integrations/schemas/categories.json b/integrations/schemas/categories.json
index 1814fb3331..27e6c13513 100644
--- a/integrations/schemas/categories.json
+++ b/integrations/schemas/categories.json
@@ -11,9 +11,7 @@
       "description": "An entry for a single category.",
       "properties": {
         "id": {
-          "type": "string",
-          "minLength": 1,
-          "description": "A unique ID for the category. Recommended format is a dot-separated list of categories that are parents of this category, followed by a unique value for this category. Must be URL safe."
+          "$ref": "./shared.json#/$defs/id"
         },
         "name": {
           "type": "string",
diff --git a/integrations/schemas/collection-single-module.json b/integrations/schemas/collection-single-module.json
index 3893249f8e..24ae47cfcb 100644
--- a/integrations/schemas/collection-single-module.json
+++ b/integrations/schemas/collection-single-module.json
@@ -211,171 +211,7 @@
       ]
     },
     "setup": {
-      "type": "object",
-      "description": "Complete information that is needed to enable and configure the data collector.",
-      "properties": {
-        "prerequisites": {
-          "type": "object",
-          "description": "Actions the user must take to make the collector work, if any. It includes both configuring Netdata (e.g. if the collector is disabled by default) and configuring the monitored instance (e.g. enabling Apache mod_stats).",
-          "properties": {
-            "list": {
-              "type": "array",
-              "description": "List of prerequisites.",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "title": {
-                    "type": "string",
-                    "description": "Title should reflect the description, be short and in the form of a command (e.g. Create netdata user, Enable build-in web server)."
-                  },
-                  "description": {
-                    "type": "string",
-                    "description": "Steps to follow to meet this prerequisite."
-                  }
-                },
-                "required": [
-                  "title",
-                  "description"
-                ]
-              }
-            }
-          },
-          "required": [
-            "list"
-          ]
-        },
-        "configuration": {
-          "description": "Information on how to configure the collector and available configuration options.",
-          "type": "object",
-          "properties": {
-            "file": {
-              "type": "object",
-              "description": "Configuration file.",
-              "properties": {
-                "name": {
-                  "type": "string",
-                  "description": "Configuration file name."
-                },
-                "section_name": {
-                  "type": "string",
-                  "description": "The name of the section in the configuration file. Only for data collectors whose configuration is in netdata.conf (e.g. proc.plugin modules)."
-                }
-              },
-              "required": [
-                "name"
-              ]
-            },
-            "options": {
-              "type": "object",
-              "description": "All information about the available configuration options.",
-              "properties": {
-                "description": {
-                  "type": "string",
-                  "description": "Optional common information about options."
-                },
-                "folding": {
-                  "$ref": "#/$defs/_folding"
-                },
-                "list": {
-                  "type": "array",
-                  "description": "List of configuration options.",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name": {
-                        "type": "string",
-                        "description": "Option name."
-                      },
-                      "description": {
-                        "type": "string",
-                        "description": "Option description. Must be short. Use 'detailed_description' for a long description."
-                      },
-                      "detailed_description": {
-                        "type": "string",
-                        "description": "Option detailed description. Use it to describe in details complex options."
-                      },
-                      "default_value": {
-                        "type": [
-                          "string",
-                          "number",
-                          "boolean"
-                        ],
-                        "description": "Default value. Leave empty if none."
-                      },
-                      "required": {
-                        "type": "boolean",
-                        "description": "Indicates whether this option is required or not. The option is required if the collector does not work, if it is not set."
-                      }
-                    },
-                    "required": [
-                      "name",
-                      "description",
-                      "default_value",
-                      "required"
-                    ]
-                  }
-                }
-              },
-              "required": [
-                "description",
-                "folding",
-                "list"
-              ]
-            },
-            "examples": {
-              "type": "object",
-              "description": "Configuration examples. The more examples the better!",
-              "properties": {
-                "folding": {
-                  "$ref": "#/$defs/_folding"
-                },
-                "list": {
-                  "type": "array",
-                  "description": "List of configuration examples.",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name": {
-                        "type": "string",
-                        "description": "Example name."
-                      },
-                      "folding": {
-                        "$ref": "#/$defs/_folding_relaxed"
-                      },
-                      "description": {
-                        "type": "string",
-                        "description": "Example description."
-                      },
-                      "config": {
-                        "type": "string",
-                        "description": "Example configuration."
-                      }
-                    },
-                    "required": [
-                      "name",
-                      "description",
-                      "config"
-                    ]
-                  }
-                }
-              },
-              "required": [
-                "folding",
-                "list"
-              ]
-            }
-          },
-          "required": [
-            "file",
-            "options",
-            "examples"
-          ]
-        }
-      },
-      "required": [
-        "prerequisites",
-        "configuration"
-      ]
+      "$ref": "./shared.json#/$defs/setup"
     },
     "troubleshooting": {
       "type": "object",
@@ -457,7 +293,7 @@
       "description": "Collected metrics grouped by scope. The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.",
       "properties": {
         "folding": {
-          "$ref": "#/$defs/_folding"
+          "$ref": "./shared.json#/$defs/_folding"
         },
         "description": {
           "type": "string",
@@ -592,42 +428,5 @@
     "troubleshooting",
     "alerts",
     "metrics"
-  ],
-  "$defs": {
-    "_folding": {
-      "type": "object",
-      "description": "Content folding settings.",
-      "properties": {
-        "title": {
-          "description": "Folded content summary title.",
-          "type": "string"
-        },
-        "enabled": {
-          "description": "Determines if this content should be folded.",
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "title",
-        "enabled"
-      ]
-    },
-    "_folding_relaxed": {
-      "type": "object",
-      "description": "Content folding settings with optional title.",
-      "properties": {
-        "title": {
-          "description": "Folded content summary title.",
-          "type": "string"
-        },
-        "enabled": {
-          "description": "Determines if this content should be folded.",
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "enabled"
-      ]
-    }
-  }
+  ]
 }
diff --git a/integrations/schemas/deploy.json b/integrations/schemas/deploy.json
index fc07c6a334..9d605aa700 100644
--- a/integrations/schemas/deploy.json
+++ b/integrations/schemas/deploy.json
@@ -7,8 +7,7 @@
     "description": "Individual entries for deployment information.",
     "properties": {
       "id": {
-        "type": "string",
-        "description": "A unique ID for this integration."
+        "$ref": "./shared.json#/$defs/id"
       },
       "meta": {
         "$ref": "./shared.json#/$defs/instance"
diff --git a/integrations/schemas/exporter.json b/integrations/schemas/exporter.json
new file mode 100644
index 0000000000..bb4ac22876
--- /dev/null
+++ b/integrations/schemas/exporter.json
@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Netdata Agent data exporter metadata.",
+  "properties": {
+    "id": {
+      "$ref": "./shared.json#/$defs/id"
+    },
+    "meta": {
+      "$ref": "./shared.json#/$defs/instance"
+    },
+    "keywords": {
+      "$ref": "./shared.json#/$defs/keywords"
+    },
+    "overview": {
+      "type": "object",
+      "description": "General information about the exporter.",
+      "properties": {
+        "exporter_description": {
+          "type": "string",
+          "description": "General description of what the exporter does."
+        },
+        "exporter_limitations": {
+          "type": "string",
+          "description": "Explanation of any limitations of the exporter."
+        }
+      },
+      "required": [
+        "exporter_description",
+        "exporter_limitations"
+      ]
+    },
+    "setup": {
+      "$ref": "./shared.json#/$defs/setup"
+    }
+  },
+  "required": [
+    "id",
+    "meta",
+    "keywords",
+    "overview",
+    "setup"
+  ]
+}
diff --git a/integrations/schemas/shared.json b/integrations/schemas/shared.json
index 776872ae76..3ee4a1c7fd 100644
--- a/integrations/schemas/shared.json
+++ b/integrations/schemas/shared.json
@@ -2,6 +2,11 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Shared definitions used for all integrations schemas.",
   "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A unique ID for the item. Must be URL safe."
+    },
     "instance": {
       "type": "object",
       "description": "Information about the integration instance.",
@@ -40,6 +45,208 @@
       "items": {
         "type": "string"
       }
+    },
+    "setup": {
+      "type": "object",
+      "description": "Complete information that is needed to enable and configure the integration.",
+      "properties": {
+        "prerequisites": {
+          "type": "object",
+          "description": "Actions the user must take to make the integration work, if any. It includes both configuring Netdata (e.g. if the integration is disabled by default) and configuring any external components the integration interacts with.",
+          "properties": {
+            "list": {
+              "type": "array",
+              "description": "List of prerequisites.",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "title": {
+                    "type": "string",
+                    "description": "Title should reflect the description, be short and in the form of a command (e.g. Create netdata user, Enable build-in web server)."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Steps to follow to meet this prerequisite."
+                  }
+                },
+                "required": [
+                  "title",
+                  "description"
+                ]
+              }
+            }
+          },
+          "required": [
+            "list"
+          ]
+        },
+        "configuration": {
+          "description": "Information on how to configure the integration and available configuration options.",
+          "type": "object",
+          "properties": {
+            "file": {
+              "type": "object",
+              "description": "Configuration file.",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "Configuration file name."
+                },
+                "section_name": {
+                  "type": "string",
+                  "description": "The name of the section in the configuration file. Only for data collectors whose configuration is in netdata.conf (e.g. proc.plugin modules)."
+                }
+              },
+              "required": [
+                "name"
+              ]
+            },
+            "options": {
+              "type": "object",
+              "description": "All information about the available configuration options.",
+              "properties": {
+                "description": {
+                  "type": "string",
+                  "description": "Optional common information about options."
+                },
+                "folding": {
+                  "$ref": "./shared.json#/$defs/_folding"
+                },
+                "list": {
+                  "type": "array",
+                  "description": "List of configuration options.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "type": "string",
+                        "description": "Option name."
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "Option description. Must be short. Use 'detailed_description' for a long description."
+                      },
+                      "detailed_description": {
+                        "type": "string",
+                        "description": "Option detailed description. Use it to describe in details complex options."
+                      },
+                      "default_value": {
+                        "type": [
+                          "string",
+                          "number",
+                          "boolean"
+                        ],
+                        "description": "Default value. Leave empty if none."
+                      },
+                      "required": {
+                        "type": "boolean",
+                        "description": "Indicates whether this option is required or not. The option is required if the integration does not work if it is not set."
+                      }
+                    },
+                    "required": [
+                      "name",
+                      "description",
+                      "default_value",
+                      "required"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "description",
+                "folding",
+                "list"
+              ]
+            },
+            "examples": {
+              "type": "object",
+              "description": "Configuration examples. The more examples the better!",
+              "properties": {
+                "folding": {
+                  "$ref": "./shared.json#/$defs/_folding"
+                },
+                "list": {
+                  "type": "array",
+                  "description": "List of configuration examples.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "type": "string",
+                        "description": "Example name."
+                      },
+                      "folding": {
+                        "$ref": "./shared.json#/$defs/_folding_relaxed"
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "Example description."
+                      },
+                      "config": {
+                        "type": "string",
+                        "description": "Example configuration."
+                      }
+                    },
+                    "required": [
+                      "name",
+                      "description",
+                      "config"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "folding",
+                "list"
+              ]
+            }
+          },
+          "required": [
+            "file",
+            "options",
+            "examples"
+          ]
+        }
+      },
+      "required": [
+        "prerequisites",
+        "configuration"
+      ]
+    },
+    "_folding": {
+      "type": "object",
+      "description": "Content folding settings.",
+      "properties": {
+        "title": {
+          "description": "Folded content summary title.",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "Determines if this content should be folded.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "title",
+        "enabled"
+      ]
+    },
+    "_folding_relaxed": {
+      "type": "object",
+      "description": "Content folding settings with optional title.",
+      "properties": {
+        "title": {
+          "description": "Folded content summary title.",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "Determines if this content should be folded.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "enabled"
+      ]
     }
   }
 }