Yamale Documentation

By default, Yamale is in strict mode, meaning it will error if unexpected elements are present in lists or maps.

• CLI: Use --no-strict to disable strict mode.
• API: Pass strict=False to the validate() function.
• Granular Control: You can set strict=True/False within specific include() validators to control behavior for included structures only.

Schema files can contain multiple YAML documents separated by ---. The first document is the base schema; subsequent documents are treated as Includes. You can use the include('name') validator to reference these definitions, allowing for code reuse and recursion.

person1: include('person')
person2: include('person')
---
person:
    name: str()
    age: int()

A schema is a valid YAML file where each node terminates in a string containing a Yamale validator. By default, all nodes are required. Use required=False to make a node optional, and none=False to reject None values for optional nodes.

name: str()
age: int(max=200)
height: num()
awesome: bool()

When writing unit tests, inherit from YamaleTestCase to simplify YAML validation within your test suite.

class TestYaml(YamaleTestCase):
    base_dir = os.path.dirname(os.path.realpath(__file__))
    schema = 'schema.yaml'
    yaml = 'data.yaml'
    # or yaml = ['data-*.yaml', 'some_data.yaml']

    def runTest(self):
        self.assertTrue(self.validate())

Install the core package using pip. You can optionally include ruamel.yaml as a dependency for better YAML 1.2 support.

$ pip install yamale
# or to include ruamel.yaml as a dependency
$ pip install yamale[ruamel]

You can integrate Yamale into your Python code by creating schema and data objects and then validating them. If validation fails, Yamale raises a ValueError (or more specifically a YamaleError which contains detailed results).

import yamale

# Import Yamale and make a schema object:
schema = yamale.make_schema('./schema.yaml')

# Create a Data object
data = yamale.make_data('./data.yaml')

# Validate data against the schema. Throws a ValueError if data is invalid.
try:
    yamale.validate(schema, data)
    print('Validation success! 👍')
except yamale.YamaleError as e:
    print('Validation failed!\n')
    for result in e.results:
        print("Error validating data '%s' with '%s'\n\t" % (result.data, result.schema))
        for error in result.errors:
            print('\t%s' % error)
    exit(1)

You can extend Yamale by subclassing yamale.validators.Validator and adding it to the validators dictionary passed to make_schema().

import yamale
import datetime
from yamale.validators import DefaultValidators, Validator

class Date(Validator):
    """ Custom Date validator """
    tag = 'date'

    def _is_valid(self, value):
        return isinstance(value, datetime.date)

validators = DefaultValidators.copy()
validators[Date.tag] = Date
schema = yamale.make_schema('./schema.yaml', validators=validators)

Instead of passing file paths to make_schema() and make_data(), you can pass raw YAML strings using the content= parameter.

data = yamale.make_data(content="""
name: Bill
age: 26
height: 6.2
awesome: True
""")

Yamale can be run from the command line to validate one or many YAML files. It searches the provided path (defaulting to the current directory) for YAML files and looks for a schema in the same directory or up the directory tree.

Options:

• -s, --schema SCHEMA: Filename of schema. Default is schema.yaml.
• -e, --exclude PATTERN: Python regex used to exclude files from validation.
• -p, --parser PARSER: YAML library to load files. Choices are ruamel or pyyaml (default).
• -n, --cpu-num CPU_NUM: Number of child processes to spawn. Default is 4. Use auto for CPU count.
• -x, --no-strict: Disable strict mode (accepts unexpected elements).
• -v, --verbose: Show verbose information.
• -V, --version: Show version number.

usage: yamale [-h] [-s SCHEMA] [-e PATTERN] [-p PARSER] [-n CPU_NUM] [-x] [-v] [-V] [PATH ...]