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.

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.
  • min-spaces-inside-empty defines the minimal number of spaces required inside empty braces.
  • max-spaces-inside-empty defines the maximal number of spaces allowed inside empty braces.

Examples

  1. 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 }
    
  2. 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 }
    
  3. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty: 0}

    the following code snippet would PASS:

    object: {}
    

    the following code snippet would FAIL:

    object: { }
    
  4. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty: -1}

    the following code snippet would PASS:

    object: {         }
    

    the following code snippet would FAIL:

    object: {}
    

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.
  • min-spaces-inside-empty defines the minimal number of spaces required inside empty brackets.
  • max-spaces-inside-empty defines the maximal number of spaces allowed inside empty brackets.

Examples

  1. 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 ]
    
  2. 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 ]
    
  3. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty: 0}

    the following code snippet would PASS:

    object: []
    

    the following code snippet would FAIL:

    object: [ ]
    
  4. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty: -1}

    the following code snippet would PASS:

    object: [         ]
    

    the following code snippet would FAIL:

    object: []
    

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

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

    the following code snippet would PASS:

    object:
      - a
      - b
    key: value
    
  2. With colons: {max-spaces-before: 1}

    the following code snippet would PASS:

    object :
      - a
      - b
    

    the following code snippet would FAIL:

    object  :
      - a
      - b
    
  3. 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

  1. 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}]
    
  2. With commas: {max-spaces-before: 2}

    the following code snippet would PASS:

    strange var:
      [10  , 20 , 30,  {x: 1  , y: 2}]
    
  3. With commas: {max-spaces-before: -1}

    the following code snippet would PASS:

    strange var:
      [10,
       20   , 30
       ,   {x: 1, y: 2}]
    
  4. 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}]
    
  5. 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}]
    
  6. 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 true to enable, false to disable.
  • Use ignore-shebangs to ignore a shebang at the beginning of the file when require-starting-space is set.
  • 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

  1. With comments: {require-starting-space: true}

    the following code snippet would PASS:

    # This sentence
    # is a block comment
    

    the following code snippet would PASS:

    ##############################
    ## This is some documentation
    

    the following code snippet would FAIL:

    #This sentence
    #is a block comment
    
  2. 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

  1. 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 true when the document end marker is required, or to false when it is forbidden.

Examples

  1. With document-end: {present: true}

    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
    ...
    
  2. With document-end: {present: false}

    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 true when the document start marker is required, or to false when it is forbidden.

Examples

  1. With document-start: {present: true}

    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
    
  2. With document-start: {present: false}

    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

  1. 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]
    

empty-values

Use this rule to prevent nodes with empty content, that implicitly result in null values.

Options

  • Use forbid-in-block-mappings to prevent empty values in block mappings.
  • Use forbid-in-flow-mappings to prevent empty values in flow mappings.

Examples

  1. With empty-values: {forbid-in-block-mappings: true}

    the following code snippets would PASS:

    some-mapping:
      sub-element: correctly indented
    
    explicitly-null: null
    

    the following code snippets would FAIL:

    some-mapping:
    sub-element: incorrectly indented
    
    implicitly-null:
    
  2. With empty-values: {forbid-in-flow-mappings: true}

    the following code snippet would PASS:

    {prop: null}
    {a: 1, b: 2, c: 3}
    

    the following code snippets would FAIL:

    {prop: }
    
    {a: 1, b:, c: 3}
    

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

  1. 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
    
  2. 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: true, false, whatever and consistent. consistent requires either all block sequences to be indented, or none to be. whatever means either indenting or not indenting individual block sequences is OK.
  • check-multi-line-strings defines whether to lint indentation in multi-line strings. Set to true to enable, false to disable.

Examples

  1. With indentation: {spaces: 1}

    the following code snippet would PASS:

    history:
     - name: Unix
       date: 1969
     - name: Linux
       date: 1991
    nest:
     recurse:
      - haystack:
         needle
    
  2. 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
    
  3. 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
    
  4. With indentation: {spaces: 2, indent-sequences: false}

    the following code snippet would PASS:

    list:
    - flying
    - spaghetti
    - monster
    

    the following code snippet would FAIL:

    list:
      - flying
      - spaghetti
      - monster
    
  5. With indentation: {spaces: 2, indent-sequences: whatever}

    the following code snippet would PASS:

    list:
    - flying:
      - spaghetti
      - monster
    - not flying:
        - spaghetti
        - sauce
    
  6. With indentation: {spaces: 2, indent-sequences: consistent}

    the following code snippet would PASS:

    - flying:
      - spaghetti
      - monster
    - not flying:
      - spaghetti
      - sauce
    

    the following code snippet would FAIL:

    - flying:
        - spaghetti
        - monster
    - not flying:
      - spaghetti
      - sauce
    
  7. With indentation: {spaces: 4, check-multi-line-strings: true}

    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

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

key-ordering

Use this rule to enforce alphabetical ordering of keys in mappings. The sorting order uses the Unicode code point number. As a result, the ordering is case-sensitive and not accent-friendly (see examples below).

Examples

  1. With key-ordering: {}

    the following code snippet would PASS:

    - key 1: v
      key 2: val
      key 3: value
    - {a: 1, b: 2, c: 3}
    - T-shirt: 1
      T-shirts: 2
      t-shirt: 3
      t-shirts: 4
    - hair: true
      hais: true
      haïr: true
      haïssable: true
    

    the following code snippet would FAIL:

    - key 2: v
      key 1: val
    

    the following code snippet would FAIL:

    - {b: 1, a: 2}
    

    the following code snippet would FAIL:

    - T-shirt: 1
      t-shirt: 2
      T-shirts: 3
      t-shirts: 4
    

    the following code snippet would FAIL:

    - haïr: true
      hais: true
    

line-length

Use this rule to set a limit to lines length.

Note: with Python 2, the line-length rule may not work properly with unicode characters because of the way strings are represented in bytes. We recommend running yamllint with Python 3.

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 true to allow, false to forbid.
  • allow-non-breakable-inline-mappings implies allow-non-breakable-words and extends it to also allow non-breakable words in inline mappings.

Examples

  1. 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.
    
  2. With line-length: {max: 60, allow-non-breakable-words: true}

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

    and the following code snippet would also FAIL:

    - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
    
  3. With line-length: {max: 60, allow-non-breakable-words: true, allow-non-breakable-inline-mappings: true}

    the following code snippet would PASS:

    - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
    
  4. With line-length: {max: 60, allow-non-breakable-words: false}

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

octal-values

Use this rule to prevent values with octal numbers. In YAML, numbers that start with 0 are interpreted as octal, but this is not always wanted. For instance 010 is the city code of Beijing, and should not be converted to 8.

Examples

  1. With octal-values: {forbid-implicit-octal: true}

    the following code snippets would PASS:

    user:
      city-code: '010'
    

    the following code snippets would PASS:

    user:
      city-code: 010,021
    

    the following code snippets would FAIL:

    user:
      city-code: 010
    
  2. With octal-values: {forbid-explicit-octal: true}

    the following code snippets would PASS:

    user:
      city-code: '0o10'
    

    the following code snippets would FAIL:

    user:
      city-code: 0o10
    

quoted-strings

Use this rule to forbid any string values that are not quoted. You can also enforce the type of the quote used using the quote-type option (single, double or any).

Note: Multi-line strings (with | or >) will not be checked.

Examples

  1. With quoted-strings: {quote-type: any}

    the following code snippet would PASS:

    foo: "bar"
    bar: 'foo'
    number: 123
    boolean: true
    

    the following code snippet would FAIL:

    foo: bar
    

trailing-spaces

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

Examples

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

truthy

Use this rule to forbid non-explictly typed truthy values other than allowed ones (by default: true and false), for example YES or off.

This can be useful to prevent surprises from YAML parsers transforming [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3, true: 4, True: 5} into {y: 1, true: 5}.

Options

  • allowed-values defines the list of truthy values which will be ignored during linting. The default is ['true', 'false'], but can be changed to any list containing: 'TRUE', 'True', 'true', 'FALSE', 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On', 'on', 'OFF', 'Off', 'off'.

Examples

  1. With truthy: {}

    the following code snippet would PASS:

    boolean: true
    
    object: {"True": 1, 1: "True"}
    
    "yes":  1
    "on":   2
    "True": 3
    
     explicit:
       string1: !!str True
       string2: !!str yes
       string3: !!str off
       encoded: !!binary |
                  True
                  OFF
                  pad==  # this decodes as 'N»ž8Qii'
       boolean1: !!bool true
       boolean2: !!bool "false"
       boolean3: !!bool FALSE
       boolean4: !!bool True
       boolean5: !!bool off
       boolean6: !!bool NO
    

    the following code snippet would FAIL:

    object: {True: 1, 1: True}
    

    the following code snippet would FAIL:

    yes:  1
    on:   2
    True: 3
    
  2. With truthy: {allowed-values: ["yes", "no"]}

    the following code snippet would PASS:

    - yes
    - no
    - "true"
    - 'false'
    - foo
    - bar
    

    the following code snippet would FAIL:

    - true
    - false
    - on
    - off