Skip to content

Commit c95f890

Browse files
Bikappaper1234
Bikappa
and
per1234
authored
chore: added json schema for configuration file (#2068)
Co-authored-by: per1234 <[email protected]>
1 parent aeacc50 commit c95f890

13 files changed

+220
-2
lines changed

Diff for: ‎.github/PULL_REQUEST_TEMPLATE.md

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ See [how to contribute](https://arduino.github.io/arduino-cli/latest/CONTRIBUTIN
99
- [ ] Tests for the changes have been added (for bug fixes / features)
1010
- [ ] Docs have been added / updated (for bug fixes / features)
1111
- [ ] `UPGRADING.md` has been updated with a migration guide (for breaking changes)
12+
- [ ] `configuration.schema.json` updated if new parameters are added.
1213

1314
## What kind of change does this PR introduce?
1415

Diff for: ‎.github/workflows/publish-go-nightly-task.yml

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ jobs:
3636
- Linux_ARM64
3737
- macOS_64bit
3838
- macOS_ARM64
39+
- jsonschema
3940

4041
steps:
4142
- name: Checkout repository

Diff for: ‎.github/workflows/publish-go-tester-task.yml

+3-1
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,9 @@ jobs:
111111
- task: protoc:collect
112112
path: "*_proto.zip"
113113
name: rpc-protocol-files
114+
- task: dist:jsonschema
115+
path: "*configuration.schema.json"
116+
name: configuration-schema
114117

115118
steps:
116119
- name: Checkout repository
@@ -146,7 +149,6 @@ jobs:
146149
steps:
147150
- name: Download build artifacts
148151
uses: actions/download-artifact@v3
149-
150152
- name: Output checksum
151153
run: |
152154
TAG="${{ needs.package-name-prefix.outputs.prefix }}git-snapshot"

Diff for: ‎.github/workflows/release-go-task.yml

+4-1
Original file line numberDiff line numberDiff line change
@@ -253,8 +253,11 @@ jobs:
253253
- name: Collect proto files
254254
run: task protoc:collect
255255

256+
- name: Add configuration JSON schema
257+
run: task dist:jsonschema
258+
256259
- name: Create checksum file
257-
working-directory: ${{ env.DIST_DIR}}
260+
working-directory: ${{ env.DIST_DIR }}
258261
run: |
259262
TAG=${{ needs.create-release-artifacts.outputs.version }}
260263
sha256sum ${{ env.PROJECT_NAME }}_${TAG}* > ${TAG}-checksums.txt

Diff for: ‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ venv
2828
/docsgen/arduino-cli.exe
2929
/docs/rpc/*.md
3030
/docs/commands/*.md
31+
/docs/configuration.schema.json
3132

3233
# Delve debugger binary file
3334
__debug_bin

Diff for: ‎DistTasks.yml

+6
Original file line numberDiff line numberDiff line change
@@ -251,3 +251,9 @@ tasks:
251251
CONTAINER_TAG: "{{.GO_VERSION}}-darwin-arm64-debian10"
252252
PACKAGE_PLATFORM: "macOS_ARM64"
253253
PACKAGE_NAME: "{{.PROJECT_NAME}}_{{.VERSION}}_{{.PACKAGE_PLATFORM}}.tar.gz"
254+
255+
jsonschema:
256+
desc: Copy the JSON schema to dist folder
257+
cmds:
258+
- mkdir --parents {{.DIST_DIR}}
259+
- cp ./configuration/configuration.schema.json {{.DIST_DIR}}/{{.PROJECT_NAME}}_{{.VERSION}}_configuration.schema.json

Diff for: ‎Taskfile.yml

+6
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ tasks:
99
deps:
1010
- task: go:cli-docs
1111
- task: protoc:docs
12+
- task: docs:include-configuration-json-schema
1213
cmds:
1314
- task: general:format-prettier
1415

@@ -218,6 +219,11 @@ tasks:
218219
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/cc/arduino/cli/settings/v1/*.proto'
219220
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/cc/arduino/cli/debug/v1/*.proto'
220221

222+
docs:include-configuration-json-schema:
223+
desc: Copy configuration JSON schema to make it available in documentation
224+
cmds:
225+
- cp ./configuration/configuration.schema.json ./docs/configuration.schema.json
226+
221227
protoc:check:
222228
desc: Perform linting of the protobuf definitions
223229
cmds:

Diff for: ‎configuration/configuration.schema.json

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
{
2+
"title": "Arduino CLI configuration schema",
3+
"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",
4+
"$schema": "http://json-schema.org/draft-06/schema#",
5+
"properties": {
6+
"board_manager": {
7+
"description": "",
8+
"properties": {
9+
"additional_urls": {
10+
"description": "the URLs to any additional Boards Manager package index files needed for your boards platforms.",
11+
"type": "array",
12+
"items": {
13+
"type": "string",
14+
"format": "uri"
15+
}
16+
}
17+
},
18+
"type": "object"
19+
},
20+
"build_cache": {
21+
"description": "configuration options related to the compilation cache",
22+
"properties": {
23+
"compilations_before_purge": {
24+
"description": "interval, in number of compilations, at which the cache is purged, defaults to `10`. When `0` the cache is never purged.",
25+
"type": "integer",
26+
"minimum": 0
27+
},
28+
"ttl": {
29+
"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)",
30+
"oneOf": [
31+
{
32+
"type": "integer",
33+
"minimum": 0
34+
},
35+
{
36+
"type": "string",
37+
"pattern": "^\\+?([0-9]?\\.?[0-9]+(([nuµm]?s)|m|h))+$"
38+
}
39+
]
40+
}
41+
},
42+
"type": "object"
43+
},
44+
"daemon": {
45+
"description": "options related to running Arduino CLI as a [gRPC] server.",
46+
"properties": {
47+
"port": {
48+
"description": "TCP port used for gRPC client connections.",
49+
"type": "string",
50+
"pattern": "^[0-9]+$"
51+
}
52+
},
53+
"type": "object"
54+
},
55+
"directories": {
56+
"description": "directories used by Arduino CLI.",
57+
"properties": {
58+
"builtin": {
59+
"description": "",
60+
"properties": {
61+
"libraries": {
62+
"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.",
63+
"type": "string"
64+
},
65+
"tools": {
66+
"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.",
67+
"type": "array",
68+
"items": {
69+
"type": "string"
70+
}
71+
}
72+
},
73+
"type": "object"
74+
},
75+
"data": {
76+
"description": "directory used to store Boards/Library Manager index files and Boards Manager platform installations.",
77+
"type": "string"
78+
},
79+
"downloads": {
80+
"description": "directory used to stage downloaded archives during Boards/Library Manager installations.",
81+
"type": "string"
82+
},
83+
"user": {
84+
"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.",
85+
"type": "string"
86+
}
87+
},
88+
"type": "object"
89+
},
90+
"library": {
91+
"description": "configuration options relating to Arduino libraries.",
92+
"properties": {
93+
"enable_unsafe_install": {
94+
"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.",
95+
"type": "boolean"
96+
}
97+
},
98+
"type": "object"
99+
},
100+
"locale": {
101+
"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`).",
102+
"type": "string"
103+
},
104+
"logging": {
105+
"description": "configuration options for Arduino CLI's logs.",
106+
"properties": {
107+
"file": {
108+
"description": "path to the file where logs will be written.",
109+
"type": "string"
110+
},
111+
"format": {
112+
"description": "output format for the logs. Allowed values are `text` or `json`.",
113+
"type": "string",
114+
"enum": ["text", "json"]
115+
},
116+
"level": {
117+
"description": "messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.",
118+
"type": "string",
119+
"enum": ["trace", "debug", "info", "warn", "error", "fatal", "panic"]
120+
}
121+
},
122+
"type": "object"
123+
},
124+
"metrics": {
125+
"description": "settings related to the collection of data used for continued improvement of Arduino CLI.",
126+
"properties": {
127+
"addr": {
128+
"description": "TCP port used for metrics communication.",
129+
"type": "string"
130+
},
131+
"enabled": {
132+
"description": "controls the use of metrics.",
133+
"type": "boolean"
134+
}
135+
},
136+
"type": "object"
137+
},
138+
"sketch": {
139+
"description": "configuration options relating to [Arduino sketches][sketch specification].",
140+
"properties": {
141+
"always_export_binaries": {
142+
"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.",
143+
"type": "boolean"
144+
}
145+
},
146+
"type": "object"
147+
},
148+
"updater": {
149+
"description": "configuration options related to Arduino CLI updates",
150+
"properties": {
151+
"enable_notification": {
152+
"description": "set to `false` to disable notifications of new Arduino CLI releases, defaults to `true`",
153+
"type": "boolean",
154+
"default": true
155+
}
156+
},
157+
"type": "object"
158+
}
159+
},
160+
"type": "object"
161+
}

Diff for: ‎configuration/configuration_schema_test.go

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
package configuration
2+
3+
import (
4+
"io/ioutil"
5+
"testing"
6+
7+
"github.com/stretchr/testify/require"
8+
"github.com/xeipuuv/gojsonschema"
9+
)
10+
11+
func TestConfigurationSchemaValidity(t *testing.T) {
12+
schemaBytes, err := ioutil.ReadFile("configuration.schema.json")
13+
require.NoError(t, err)
14+
15+
jl := gojsonschema.NewBytesLoader(schemaBytes)
16+
sl := gojsonschema.NewSchemaLoader()
17+
_, err = sl.Compile(jl)
18+
require.NoError(t, err)
19+
}

Diff for: ‎docs/configuration.md

+6
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,11 @@ Doing the same using a TOML format file:
146146
additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index.json" ]
147147
```
148148

149+
#### JSON schema
150+
151+
The configuration file [JSON schema][configuration-schema] can be used to independently validate the file content. This
152+
schema should be considered unstable in this version.
153+
149154
[grpc]: https://grpc.io
150155
[sketchbook directory]: sketch-specification.md#sketchbook
151156
[arduino cli lib install]: commands/arduino-cli_lib_install.md
@@ -164,3 +169,4 @@ additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index
164169
[java properties file]: https://en.wikipedia.org/wiki/.properties
165170
[hcl]: https://github.com/hashicorp/hcl
166171
[ini]: https://en.wikipedia.org/wiki/INI_file
172+
[configuration-schema]: ./configuration.schema.json

Diff for: ‎docsgen/go.sum

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

Diff for: ‎go.mod

+3
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ require (
4949

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

Diff for: ‎go.sum

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

0 commit comments

Comments
 (0)