Create schema documentation to describe all Fleet configuration options in YAML and/or JSON format

[ddribeiro]

Problem

Currently, when building my Fleet configuration files, I need to generate them myself and validate them manually. This workflow is error prone and might require trial and error to get right, especially if I'm unfamiliar with the options available to me in Fleet's configuration options.

I want Fleet to maintain a schema in YAML or JSON format to describe all possible configuration options across the Fleet product.

What have you tried?

When using configuration files in Fleet, it can be difficult to know exactly what options are available to me and what data types are expected as values for each option.

Currently, I rely on documentation on the Fleet website for server configuration, and agent configuration.

This documentation provides a human readable reference that shows an admin what configuration keys and values are available to use.

Having a YAML schema is machine readable and can be provided to an IDE to validate my configuration files. It could also be used to generate valid configuration files which could lower the barrier of entry for new Fleet customers.

Potential solutions

Provide a complete schema in YAML format for all areas of Fleet where configuration files are used. Primarily, this would include server and agent configuration files and GitOps yaml files.

An example of what this looks like in practice is Apple's Device Management schema. For example if we look at the .yml file for the Erase Device MDM command, we can see supported devices, OS versions, supported keys and subkeys, if they are required, and what type of data they accept. This file can be provided to an IDE to validate Erase Device MDM commands that I build myself.

Another example I've seen is Swift's OpenAPI Generator, where an OpenAPI document (YAML or JSON) is provided to automate workflows like generating code in Swift projects.

What is the expected workflow as a result of your proposal?

I want to be able to provide a configuration schema file in YAML format to my IDE. When I do this, the following workflows can be accomplished: 1. My IDE can generate a valid Fleet configuration file based off the schema. This reduces error and improves discoverability of configuration options. 2. My IDE can use the schema file to validate an existing configuration. This includes making sure keys are nested properly and values are a valid/expected type.

[JoStableford]

Related to a Slack conversation

[noahtalerman]

Hey @ddribeiro when you get the chance, can you please check w/ the customer to help us understand the exact VS Code workflow to import a YAML schema? What buttons they click in VS Code?

[ddribeiro]

@noahtalerman customer-rosner says they'll be using https://github.com/redhat-developer/vscode-yaml to specify a custom schema for validation.