chore: added json schema for configuration file

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,6 +9,7 @@ See [how to contribute](https://arduino.github.io/arduino-cli/latest/CONTRIBUTIN
 - [ ] Tests for the changes have been added (for bug fixes / features)
 - [ ] Docs have been added / updated (for bug fixes / features)
 - [ ] `UPGRADING.md` has been updated with a migration guide (for breaking changes)
+- [ ] `configuration.schema.json` updated if new parameters are added.
 
 ## What kind of change does this PR introduce?
 

.github/workflows/publish-go-nightly-task.yml

@@ -36,6 +36,7 @@ jobs:
           - Linux_ARM64
           - macOS_64bit
           - macOS_ARM64
+          - jsonschema
 
     steps:
       - name: Checkout repository

.github/workflows/publish-go-tester-task.yml

@@ -111,6 +111,9 @@ jobs:
           - task: protoc:collect
             path: "*_proto.zip"
             name: rpc-protocol-files
+          - task: dist:jsonschema
+            path: "*configuration.schema.json"
+            name: configuration-schema
 
     steps:
       - name: Checkout repository
@@ -146,7 +149,6 @@ jobs:
     steps:
       - name: Download build artifacts
         uses: actions/download-artifact@v3
-
       - name: Output checksum
         run: |
           TAG="${{ needs.package-name-prefix.outputs.prefix }}git-snapshot"

.github/workflows/release-go-task.yml

@@ -253,8 +253,11 @@ jobs:
       - name: Collect proto files
         run: task protoc:collect
 
+      - name: Add configuration JSON schema
+        run: task dist:jsonschema
+
       - name: Create checksum file
-        working-directory: ${{ env.DIST_DIR}}
+        working-directory: ${{ env.DIST_DIR }}
         run: |
           TAG=${{ needs.create-release-artifacts.outputs.version }}
           sha256sum ${{ env.PROJECT_NAME }}_${TAG}* > ${TAG}-checksums.txt

.gitignore

@@ -28,6 +28,7 @@ venv
 /docsgen/arduino-cli.exe
 /docs/rpc/*.md
 /docs/commands/*.md
+/docs/configuration.schema.json
 
 # Delve debugger binary file
 __debug_bin

DistTasks.yml

@@ -251,3 +251,9 @@ tasks:
       CONTAINER_TAG: "{{.GO_VERSION}}-darwin-arm64-debian10"
       PACKAGE_PLATFORM: "macOS_ARM64"
       PACKAGE_NAME: "{{.PROJECT_NAME}}_{{.VERSION}}_{{.PACKAGE_PLATFORM}}.tar.gz"
+
+  jsonschema:
+    desc: Copy the JSON schema to dist folder
+    cmds:
+      - mkdir --parents {{.DIST_DIR}}
+      - cp ./configuration/configuration.schema.json {{.DIST_DIR}}/{{.PROJECT_NAME}}_{{.VERSION}}_configuration.schema.json

Taskfile.yml

@@ -9,6 +9,7 @@ tasks:
     deps:
       - task: go:cli-docs
       - task: protoc:docs
+      - task: docs:include-configuration-json-schema
     cmds:
       - task: general:format-prettier
 
@@ -218,6 +219,11 @@ tasks:
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/cc/arduino/cli/settings/v1/*.proto'
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/cc/arduino/cli/debug/v1/*.proto'
 
+  docs:include-configuration-json-schema:
+    desc: Copy configuration JSON schema to make it available in documentation
+    cmds:
+      - cp ./configuration/configuration.schema.json ./docs/configuration.schema.json
+
   protoc:check:
     desc: Perform linting of the protobuf definitions
     cmds:

configuration/configuration.schema.json

@@ -0,0 +1,161 @@
+{
+  "title": "Arduino CLI configuration schema",
+  "description": "Describe the parameters available for the Arduino CLI configuration file. This schema should be considered unstable at this moment, it is not used by the CLI to validate input configuration",
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "properties": {
+    "board_manager": {
+      "description": "",
+      "properties": {
+        "additional_urls": {
+          "description": "the URLs to any additional Boards Manager package index files needed for your boards platforms.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      },
+      "type": "object"
+    },
+    "build_cache": {
+      "description": "configuration options related to the compilation cache",
+      "properties": {
+        "compilations_before_purge": {
+          "description": "interval, in number of compilations, at which the cache is purged, defaults to `10`. When `0` the cache is never purged.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "ttl": {
+          "description": "cache expiration time of build folders. If the cache is hit by a compilation the corresponding build files lifetime is renewed. The value format must be a valid input for time.ParseDuration(), defaults to `720h` (30 days)",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "string",
+              "pattern": "^\\+?([0-9]?\\.?[0-9]+(([nuµm]?s)|m|h))+$"
+            }
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "daemon": {
+      "description": "options related to running Arduino CLI as a [gRPC] server.",
+      "properties": {
+        "port": {
+          "description": "TCP port used for gRPC client connections.",
+          "type": "string",
+          "pattern": "^[0-9]+$"
+        }
+      },
+      "type": "object"
+    },
+    "directories": {
+      "description": "directories used by Arduino CLI.",
+      "properties": {
+        "builtin": {
+          "description": "",
+          "properties": {
+            "libraries": {
+              "description": "the libraries in this directory will be available to all platforms without the need for the user to install them, but with the lowest priority over other installed libraries with the same name, it's the equivalent of the Arduino IDE's bundled libraries directory.",
+              "type": "string"
+            },
+            "tools": {
+              "description": "it's a list of directories of tools that will be available to all platforms without the need for the user to install them, it's the equivalent of the Arduino IDE 1.x bundled tools directory.",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "type": "object"
+        },
+        "data": {
+          "description": "directory used to store Boards/Library Manager index files and Boards Manager platform installations.",
+          "type": "string"
+        },
+        "downloads": {
+          "description": "directory used to stage downloaded archives during Boards/Library Manager installations.",
+          "type": "string"
+        },
+        "user": {
+          "description": "the equivalent of the Arduino IDE's [\"sketchbook\" directory][sketchbook directory]. Library Manager installations are made to the `libraries` subdirectory of the user directory.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "library": {
+      "description": "configuration options relating to Arduino libraries.",
+      "properties": {
+        "enable_unsafe_install": {
+          "description": "set to `true` to enable the use of the `--git-url` and `--zip-file` flags with [`arduino-cli lib install`][arduino cli lib install]. These are considered \"unsafe\" installation methods because they allow installing files that have not passed through the Library Manager submission process.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "locale": {
+      "description": "the language used by Arduino CLI to communicate to the user, the parameter is the language identifier in the standard POSIX format `<language>[_<TERRITORY>[.<encoding>]]` (for example `it` or `it_IT`, or `it_IT.UTF-8`).",
+      "type": "string"
+    },
+    "logging": {
+      "description": "configuration options for Arduino CLI's logs.",
+      "properties": {
+        "file": {
+          "description": "path to the file where logs will be written.",
+          "type": "string"
+        },
+        "format": {
+          "description": "output format for the logs. Allowed values are `text` or `json`.",
+          "type": "string",
+          "enum": ["text", "json"]
+        },
+        "level": {
+          "description": "messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.",
+          "type": "string",
+          "enum": ["trace", "debug", "info", "warn", "error", "fatal", "panic"]
+        }
+      },
+      "type": "object"
+    },
+    "metrics": {
+      "description": "settings related to the collection of data used for continued improvement of Arduino CLI.",
+      "properties": {
+        "addr": {
+          "description": "TCP port used for metrics communication.",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "controls the use of metrics.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "sketch": {
+      "description": "configuration options relating to [Arduino sketches][sketch specification].",
+      "properties": {
+        "always_export_binaries": {
+          "description": "set to `true` to make [`arduino-cli compile`][arduino-cli compile] always save binaries to the sketch folder. This is the equivalent of using the [`--export-binaries`][arduino-cli compile options] flag.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "updater": {
+      "description": "configuration options related to Arduino CLI updates",
+      "properties": {
+        "enable_notification": {
+          "description": "set to `false` to disable notifications of new Arduino CLI releases, defaults to `true`",
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

configuration/configuration_schema_test.go

@@ -0,0 +1,19 @@
+package configuration
+
+import (
+	"io/ioutil"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/xeipuuv/gojsonschema"
+)
+
+func TestConfigurationSchemaValidity(t *testing.T) {
+	schemaBytes, err := ioutil.ReadFile("configuration.schema.json")
+	require.NoError(t, err)
+
+	jl := gojsonschema.NewBytesLoader(schemaBytes)
+	sl := gojsonschema.NewSchemaLoader()
+	_, err = sl.Compile(jl)
+	require.NoError(t, err)
+}

docs/configuration.md

@@ -146,6 +146,11 @@ Doing the same using a TOML format file:
 additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index.json" ]
 ```
 
+#### JSON schema
+
+The configuration file [JSON schema][configuration-schema] can be used to independently validate the file content. This
+schema should be considered unstable in this version.
+
 [grpc]: https://grpc.io
 [sketchbook directory]: sketch-specification.md#sketchbook
 [arduino cli lib install]: commands/arduino-cli_lib_install.md
@@ -164,3 +169,4 @@ additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index
 [java properties file]: https://en.wikipedia.org/wiki/.properties
 [hcl]: https://github.com/hashicorp/hcl
 [ini]: https://en.wikipedia.org/wiki/INI_file
+[configuration-schema]: ./configuration.schema.json

docsgen/go.sum

@@ -331,6 +331,9 @@ github.com/ulikunitz/xz v0.5.11 h1:kpFauv27b6ynzBNT/Xy+1k+fK4WswhN/6PN5WhFAGw8=
 github.com/ulikunitz/xz v0.5.11/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
 github.com/xanzy/ssh-agent v0.2.1 h1:TCbipTQL2JiiCprBWx9frJ2eJlCYT00NmctrHxVAr70=
 github.com/xanzy/ssh-agent v0.2.1/go.mod h1:mLlQY/MoOhWBj+gOGMQkOeiEvkx+8pJSI+0Bx9h2kr4=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
+github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
 github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=

go.mod

@@ -49,6 +49,7 @@ require (
 
 require (
 	github.com/rogpeppe/go-internal v1.3.0
+	github.com/xeipuuv/gojsonschema v1.2.0
 	go.bug.st/testifyjson v1.1.1
 	golang.org/x/term v0.0.0-20210927222741-03fcf44c2211
 	gopkg.in/yaml.v3 v3.0.1
@@ -88,6 +89,8 @@ require (
 	github.com/subosito/gotenv v1.2.0 // indirect
 	github.com/ulikunitz/xz v0.5.11 // indirect
 	github.com/xanzy/ssh-agent v0.2.1 // indirect
+	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
+	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	golang.org/x/net v0.0.0-20220722155237-a158d28d115b // indirect
 	golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f // indirect
 	gopkg.in/ini.v1 v1.62.0 // indirect

go.sum

@@ -342,6 +342,12 @@ github.com/ulikunitz/xz v0.5.11 h1:kpFauv27b6ynzBNT/Xy+1k+fK4WswhN/6PN5WhFAGw8=
 github.com/ulikunitz/xz v0.5.11/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
 github.com/xanzy/ssh-agent v0.2.1 h1:TCbipTQL2JiiCprBWx9frJ2eJlCYT00NmctrHxVAr70=
 github.com/xanzy/ssh-agent v0.2.1/go.mod h1:mLlQY/MoOhWBj+gOGMQkOeiEvkx+8pJSI+0Bx9h2kr4=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
+github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
+github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
 github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=