73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# JSON Schema
|
|
|
|
| WARNING: This page describes a beta feature which is currently under development. The implementation may change in an incompatible way. Use at your own risk |
|
|
| --- |
|
|
|
|
Jenkins Configuration as Code plugin sometimes requires users to define pretty complex YAML configuration files.
|
|
At the same time, mistakes in the configuration may lead to the instance instability.
|
|
In order to help maintainers, the plugin can generate an instance-specific JSON schema which can be used for validation of YAML files.
|
|
|
|
## Current state
|
|
|
|
Currently there are 2 types of JSON schema being generated by the plugin.
|
|
There is a legacy schema generation logic which has been available since JCasC 1.0, but this feature generates an invalid JSON schema which cannot be used as is without manual patches.
|
|
In order to solve the issue, in the [JCasC Developer Tools project](https://jenkins.io/projects/jcasc/dev-tools/) we are working on a new Schema version which is currently available as a **beta feature**.
|
|
The implementation may change in an incompatible way before the final release.
|
|
|
|
The documentation below describes the new implementation.
|
|
|
|
The new JSON Schema is structured to validate the YAML files that are loaded via JCasC.
|
|
The structure and validation of the Schema is done based on the user-installed plugins.
|
|
|
|
=== Version
|
|
|
|
The Schema uses JSON draft v07.
|
|
http://json-schema.org/draft-07/schema#
|
|
|
|
=== How to use
|
|
|
|
* The schema will be available at /configuration-as-code/schema
|
|
* Users can use various online JSON validators to check against their YAML/json.
|
|
|
|
=== Progress
|
|
|
|
* The new JSON Schema is partially working and is in beta mode.
|
|
* The schema validates any missing configurator objects and invalid data formats.
|
|
* It is built around the existing executable xml (jelly files) and follows the latest draft version of JSON.
|
|
* The schema does not yet validate against deep nested configurations.
|
|
* We are working towards supporting deep nested YAML files.
|
|
|
|
== Improvements
|
|
|
|
* The Old Schema was generated using Jelly files that did not generate a valid JSON Schema.
|
|
* Without a valid schema it is not possible to validate a YAML file rendering the schema unusable.
|
|
* The previous schema included an `"$ref":` for an `object` type, the new draft of the schema makes it mandatory
|
|
to use `"$id":` hence the new schema uses it instead of ref.
|
|
|
|
== What the schema does
|
|
|
|
* The schema validates simple YAML files with root configurators.
|
|
```yaml
|
|
# config truncated
|
|
jenkins:
|
|
numExecutors: 2
|
|
```
|
|
* In the above example if the data type of numExecutors is entered wrong, the schema will invalidate it.
|
|
|
|
== What the schema does not do
|
|
|
|
* It cannot validate nested yml files, with multiple levels of configurators.
|
|
```yaml
|
|
# config truncated
|
|
jenkins:
|
|
numExecutors: 0
|
|
|
|
nodes:
|
|
- dumb:
|
|
mode: NORMAL
|
|
name: "agent1"
|
|
```
|
|
* The above YAML has a deep level of nesting which the JSON Schema currently does not support.
|
|
|
|
|