Skip to content

Latest commit

 

History

History
72 lines (51 loc) · 2.87 KB

jsonSchema.md

File metadata and controls

72 lines (51 loc) · 2.87 KB
Raw

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 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.
# 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.
# 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.