Open a command prompt and create a new directory to hold this tutorial’s files.

For example:

$ pwd # we start in our home directory, but you do not need to
/home/runner
$ mkdir validating-yaml-with-cue
$ cd validating-yaml-with-cue

Create a data file named charlie.yml to hold Charlie the cat’s details.

Place this information in it, including the deliberate mistake in the species field:

name:
  first: Charlie
  last:  Cartwright
species: goldfish
age: "15"

Create a file called pets.cue to hold your schema, and place this CUE in it:

species!: "cat" | "dog"
age?:     number

cue will check that your data files are valid, that they satisfy this schema.

Line 1 is important because, for the purposes of this tutorial, all pets are cats or dogs, so the species field can only contain one of a fixed set of options. This is what CUE calls a disjunction, and is indicated by a pipe symbol ("|").

On line 1 the species field is marked with an exclamation mark ("!"). This means that the field must be present in the data, which CUE calls a required field.

On line 2 the age field is marked with a question mark ("?"). CUE calls this an optional field, which means that the field may present in the data, but it may not.

The age field is constrained such that, if it is present, it has to be of type number.

The number type constraint permits values that are either integers or decimal floating-point numbers. CUE has other primitive types that you can use to constrain a field’s value.

Check that the charlie.yml data file satisfies the schema you defined in pets.cue:

$ cue vet pets.cue charlie.yml
age: conflicting values "15" and number (mismatched types string and number):
    ./charlie.yml:5:6
    ./pets.cue:2:11
species: 2 errors in empty disjunction:
species: conflicting values "cat" and "goldfish":
    ./charlie.yml:4:10
    ./pets.cue:1:11
species: conflicting values "dog" and "goldfish":
    ./charlie.yml:4:10
    ./pets.cue:1:19

cue vet is telling you that there are problems with 2 fields in your data file.

Firstly, there is a conflict between what is specified for the age field in charlie.yml on line 5, and the schema’s constraints in pets.cue on line 2. cue tells you about these mismatched types, along with pointers to the files and line numbers that disagree with each other.

Looking at the files, you can see that your schema says that the age field has to be a number if it is present. In your data file the quotation marks around the number 15 mean that the value is actually a string.

Secondly, cue vet says that there are 2 errors in empty disjunction, relating to the species field. This is followed by a pair of conflicting values ... error messages pointing to the files and line numbers that are conflicting.

This is cue’s way of showing you that it compared the field’s value in the data file (goldfish) against both options permitted by your schema (dog or cat), and that it failed to find any options that matched, or unified, successfully.

Update charlie.yml to:

• Fix the type mismatch in the age field by removing both quotation marks around the value.
• Change the species field to the value cat, a valid species according to our schema.

Your corrected data file should read as follows:

name:
  first: Charlie
  last:  Cartwright
species: cat
age: 15

Re-check the data file against the CUE schema:

$ cue vet pets.cue charlie.yml

Notice how the command returns instantly, with no output.

This is how the cue vet command tells you that everything is fine: by saying nothing, and silently returning an exit code of 0 to your shell.

Add a second data file containing the details of another pet.

Create a data file named toby.yml to hold Toby the dog’s details:

name:
  first: Toby
  last: Dog
species: dog
age: 12.5

Ask cue to check that both data files satisfy your schema in pets.cue:

$ cue vet pets.cue charlie.yml toby.yml

The command’s success (and lack of any error message) confirms that both data files are valid, because both their contents are permitted by the constraints you placed in your schema.