Rules¶

When linting a document with yamllint, a series of rules (such as line-length, trailing-spaces, etc.) are checked against.

A configuration file can be used to enable or disable these rules, to set their level (error or warning), but also to tweak their options.

This page describes the rules and their options.

List of rules

braces
brackets
colons
commas
comments
comments-indentation
document-end
document-start
empty-lines
hyphens
indentation
key-duplicates
line-length
new-line-at-end-of-file
new-lines
trailing-spaces

braces ¶

Use this rule to control the number of spaces inside braces ({ and }).

Options

min-spaces-inside defines the minimal number of spaces required inside braces.
max-spaces-inside defines the maximal number of spaces allowed inside braces.

Examples

With braces: {min-spaces-inside: 0, max-spaces-inside: 0}

the following code snippet would PASS:
```
object: {key1: 4, key2: 8}
```
the following code snippet would FAIL:
```
object: { key1: 4, key2: 8 }
```
With braces: {min-spaces-inside: 1, max-spaces-inside: 3}

the following code snippet would PASS:
```
object: { key1: 4, key2: 8 }
```
the following code snippet would PASS:
```
object: { key1: 4, key2: 8   }
```
the following code snippet would FAIL:
```
object: {    key1: 4, key2: 8   }
```
the following code snippet would FAIL:
```
object: {key1: 4, key2: 8 }
```

brackets ¶

Use this rule to control the number of spaces inside brackets ([ and ]).

Options

min-spaces-inside defines the minimal number of spaces required inside brackets.
max-spaces-inside defines the maximal number of spaces allowed inside brackets.

Examples

With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}

the following code snippet would PASS:
```
object: [1, 2, abc]
```
the following code snippet would FAIL:
```
object: [ 1, 2, abc ]
```
With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}

the following code snippet would PASS:
```
object: [ 1, 2, abc ]
```
the following code snippet would PASS:
```
object: [ 1, 2, abc   ]
```
the following code snippet would FAIL:
```
object: [    1, 2, abc   ]
```
the following code snippet would FAIL:
```
object: [1, 2, abc ]
```

colons ¶

Use this rule to control the number of spaces before and after colons (:).

Options

max-spaces-before defines the maximal number of spaces allowed before colons (use -1 to disable).
max-spaces-after defines the maximal number of spaces allowed after colons (use -1 to disable).

Examples

With colons: {max-spaces-before: 0, max-spaces-after: 1}

the following code snippet would PASS:
```
object:
  - a
  - b
key: value
```
With colons: {max-spaces-before: 1}

the following code snippet would PASS:
```
object :
  - a
  - b
```
the following code snippet would FAIL:
```
object  :
  - a
  - b
```
With colons: {max-spaces-after: 2}

the following code snippet would PASS:
```
first:  1
second: 2
third:  3
```
the following code snippet would FAIL:
```
first: 1
2nd:   2
third: 3
```

commas ¶

Use this rule to control the number of spaces before and after commas (,).

Options

max-spaces-before defines the maximal number of spaces allowed before commas (use -1 to disable).
min-spaces-after defines the minimal number of spaces required after commas.
max-spaces-after defines the maximal number of spaces allowed after commas (use -1 to disable).

Examples

With commas: {max-spaces-before: 0}

the following code snippet would PASS:
```
strange var:
  [10, 20, 30, {x: 1, y: 2}]
```
the following code snippet would FAIL:
```
strange var:
  [10, 20 , 30, {x: 1, y: 2}]
```
With commas: {max-spaces-before: 2}

the following code snippet would PASS:
```
strange var:
  [10  , 20 , 30,  {x: 1  , y: 2}]
```
With commas: {max-spaces-before: -1}

the following code snippet would PASS:
```
strange var:
  [10,
   20   , 30
   ,   {x: 1, y: 2}]
```
With commas: {min-spaces-after: 1, max-spaces-after: 1}

the following code snippet would PASS:
```
strange var:
  [10, 20,30, {x: 1, y: 2}]
```
the following code snippet would FAIL:
```
strange var:
  [10, 20,30,   {x: 1,   y: 2}]
```
With commas: {min-spaces-after: 1, max-spaces-after: 3}

the following code snippet would PASS:
```
strange var:
  [10, 20,  30,  {x: 1,   y: 2}]
```
With commas: {min-spaces-after: 0, max-spaces-after: 1}

the following code snippet would PASS:
```
strange var:
  [10, 20,30, {x: 1, y: 2}]
```

comments ¶

Use this rule to control the position and formatting of comments.

Options

Use require-starting-space to require a space character right after the #. Set to yes to enable, no to disable.
min-spaces-from-content is used to visually separate inline comments from content. It defines the minimal required number of spaces between a comment and its preceding content.

Examples

With comments: {require-starting-space: yes}

the following code snippet would PASS:
```
# This sentence
# is a block comment
```
the following code snippet would FAIL:
```
#This sentence
#is a block comment
```
With comments: {min-spaces-from-content: 2}

the following code snippet would PASS:
```
x = 2 ^ 127 - 1  # Mersenne prime number
```
the following code snippet would FAIL:
```
x = 2 ^ 127 - 1 # Mersenne prime number
```

comments-indentation ¶

Use this rule to force comments to be indented like content.

Examples

With comments-indentation: {}

the following code snippet would PASS:

# Fibonacci
[0, 1, 1, 2, 3, 5]

the following code snippet would FAIL:

  # Fibonacci
[0, 1, 1, 2, 3, 5]

the following code snippet would PASS:

list:
    - 2
    - 3
    # - 4
    - 5

the following code snippet would FAIL:

list:
    - 2
    - 3
#    - 4
    - 5

the following code snippet would PASS:

# This is the first object
obj1:
  - item A
  # - item B
# This is the second object
obj2: []

the following code snippet would PASS:

# This sentence
# is a block comment

the following code snippet would FAIL:

# This sentence
 # is a block comment

document-end ¶

Use this rule to require or forbid the use of document end marker (...).

Options

Set present to yes when the document end marker is required, or to no when it is forbidden.

Examples

With document-end: {present: yes}

the following code snippet would PASS:

---
this:
  is: [a, document]
...
---
- this
- is: another one
...

the following code snippet would FAIL:

---
this:
  is: [a, document]
---
- this
- is: another one
...

With document-end: {present: no}

the following code snippet would PASS:

---
this:
  is: [a, document]
---
- this
- is: another one

the following code snippet would FAIL:

---
this:
  is: [a, document]
...
---
- this
- is: another one

document-start ¶

Use this rule to require or forbid the use of document start marker (---).

Options

Set present to yes when the document start marker is required, or to no when it is forbidden.

Examples

With document-start: {present: yes}

the following code snippet would PASS:

---
this:
  is: [a, document]
---
- this
- is: another one

the following code snippet would FAIL:

this:
  is: [a, document]
---
- this
- is: another one

With document-start: {present: no}

the following code snippet would PASS:
```
this:
  is: [a, document]
...
```
the following code snippet would FAIL:
```
---
this:
  is: [a, document]
...
```

empty-lines ¶

Use this rule to set a maximal number of allowed consecutive blank lines.

Options

max defines the maximal number of empty lines allowed in the document.
max-start defines the maximal number of empty lines allowed at the beginning of the file. This option takes precedence over max.
max-end defines the maximal number of empty lines allowed at the end of the file. This option takes precedence over max.

Examples

With empty-lines: {max: 1}

the following code snippet would PASS:
```
- foo:
    - 1
    - 2

- bar: [3, 4]
```
the following code snippet would FAIL:
```
- foo:
    - 1
    - 2


- bar: [3, 4]
```

hyphens ¶

Use this rule to control the number of spaces after hyphens (-).

Options

max-spaces-after defines the maximal number of spaces allowed after hyphens.

Examples

With hyphens: {max-spaces-after: 1}

the following code snippet would PASS:
```
- first list:
    - a
    - b
- - 1
  - 2
  - 3
```
the following code snippet would FAIL:
```
-  first list:
     - a
     - b
```
the following code snippet would FAIL:
```
- - 1
  -  2
  - 3
```
With hyphens: {max-spaces-after: 3}

the following code snippet would PASS:
```
-   key
-  key2
- key42
```
the following code snippet would FAIL:
```
-    key
-   key2
-  key42
```

indentation ¶

Use this rule to control the indentation.

Options

spaces defines the indentation width, in spaces. Set either to an integer (e.g. 2 or 4, representing the number of spaces in an indentation level) or to consistent to allow any number, as long as it remains the same within the file.
indent-sequences defines whether block sequences should be indented or not (when in a mapping, this indentation is not mandatory – some people perceive the - as part of the indentation). Possible values: yes, no and whatever (the latter means either indenting or not indenting block sequences is OK.
check-multi-line-strings defines whether to lint indentation in multi-line strings. Set to yes to enable, no to disable.

Examples

With indentation: {spaces: 1}

the following code snippet would PASS:

history:
 - name: Unix
   date: 1969
 - name: Linux
   date: 1991
nest:
 recurse:
  - haystack:
     needle

With indentation: {spaces: 4}

the following code snippet would PASS:

history:
    - name: Unix
      date: 1969
    - name: Linux
      date: 1991
nest:
    recurse:
        - haystack:
              needle

the following code snippet would FAIL:

history:
  - name: Unix
    date: 1969
  - name: Linux
    date: 1991
nest:
  recurse:
    - haystack:
        needle

With indentation: {spaces: consistent}

the following code snippet would PASS:

history:
   - name: Unix
     date: 1969
   - name: Linux
     date: 1991
nest:
   recurse:
      - haystack:
           needle

the following code snippet would FAIL:

some:
  Russian:
      dolls

With indentation: {spaces: 2, indent-sequences: no}

the following code snippet would PASS:
```
list:
- flying
- spaghetti
- monster
```
the following code snippet would FAIL:
```
list:
  - flying
  - spaghetti
  - monster
```
With indentation: {spaces: 2, indent-sequences: whatever}

the following code snippet would PASS:
```
list:
- flying:
  - spaghetti
  - monster
- not flying:
    - spaghetti
    - sauce
```

With indentation: {spaces: 4, check-multi-line-strings: yes}

the following code snippet would PASS:

Blaise Pascal:
    Je vous écris une longue lettre parce que
    je n'ai pas le temps d'en écrire une courte.

the following code snippet would PASS:

Blaise Pascal: Je vous écris une longue lettre parce que
               je n'ai pas le temps d'en écrire une courte.

the following code snippet would FAIL:

Blaise Pascal: Je vous écris une longue lettre parce que
  je n'ai pas le temps d'en écrire une courte.

the following code snippet would FAIL:

C code:
    void main() {
        printf("foo");
    }

the following code snippet would PASS:

C code:
    void main() {
    printf("bar");
    }

key-duplicates ¶

Use this rule to prevent multiple entries with the same key in mappings.

Examples

With key-duplicates: {}

the following code snippet would PASS:

- key 1: v
  key 2: val
  key 3: value
- {a: 1, b: 2, c: 3}

the following code snippet would FAIL:

- key 1: v
  key 2: val
  key 1: value

the following code snippet would FAIL:

- {a: 1, b: 2, b: 3}

the following code snippet would FAIL:

duplicated key: 1
"duplicated key": 2

other duplication: 1
? >-
    other
    duplication
: 2

line-length ¶

Use this rule to set a limit to lines length.

Options

max defines the maximal (inclusive) length of lines.
allow-non-breakable-words is used to allow non breakable words (without spaces inside) to overflow the limit. This is useful for long URLs, for instance. Use yes to allow, no to forbid.

Examples

With line-length: {max: 70}

the following code snippet would PASS:

long sentence:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
  eiusmod tempor incididunt ut labore et dolore magna aliqua.

the following code snippet would FAIL:

long sentence:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
  tempor incididunt ut labore et dolore magna aliqua.

With line-length: {max: 60, allow-non-breakable-words: yes}

the following code snippet would PASS:

this:
  is:
    - a:
        http://localhost/very/very/very/very/very/very/very/very/long/url

# this comment is too long,
# but hard to split:
# http://localhost/another/very/very/very/very/very/very/very/very/long/url

the following code snippet would FAIL:

- this line is waaaaaaaaaaaaaay too long but could be easily splitted...

With line-length: {max: 60, allow-non-breakable-words: no}

the following code snippet would FAIL:

this:
  is:
    - a:
        http://localhost/very/very/very/very/very/very/very/very/long/url

new-line-at-end-of-file ¶

Use this rule to require a new line character (\n) at the end of files.

The POSIX standard requires the last line to end with a new line character. All UNIX tools expect a new line at the end of files. Most text editors use this convention too.

new-lines ¶

Use this rule to force the type of new line characters.

Options

Set type to unix to use UNIX-typed new line characters (\n), or dos to use DOS-typed new line characters (\r\n).

trailing-spaces ¶

Use this rule to forbid trailing spaces at the end of lines.

Examples

With trailing-spaces: {}

the following code snippet would PASS:

this document doesn't contain
any trailing
spaces

the following code snippet would FAIL:

this document contains     
trailing spaces
on lines 1 and 3         