Rulya

Helps you define and apply semantic validation to a collection of YAML files. Typically used as pre-commit hook or CI/CD build step.

Usage

Create a NPM package in the directory containing the files to validate:

npm init

And set the test script to:

jasmine --require=rulya validate.js

Add Rulya as a development dependency:

npm install rulya --save-dev

Write your validation rules in validate.js:

// Traverse all YAML files in the test-data/articles directory
documents("test-data/articles/**/*.yaml", (doc, path) => {

    // Validate against a JSON schema (can be a URL as well)
    schema("test-data/articles/article.schema.json", doc);

    // Define a rule on the filename
    rule("filename", path, "must have a filename containing the string 'article'", () => {
        expect(path.split("/").slice(-1)[0]).toContain("article");
    });
});

// Traverse all YAML files in the test-data/books directory
documents("test-data/books/**/*.yaml", (doc) => {

    // Iterate through the chapters
    property("chapters", doc.chapters, chapter =>

        // Group rules applied to the chapter titles
        property("title", chapter.title, title => {

            // Define rules for the chapter titles

            rule("capitalized", title, "must start with a capital letter", () => {
                expect(title).toMatch("^[A-Z].*");
            });

            rule("letters-only", title, "must contains only letters", () => {
                expect(title).toMatch("^[A-Za-z ]*$");
            });
        }));

    // A rule can be defined standalone, the property name must be writen in the description though
    rule("page-number", doc.pages, "'pages' must be positive if present", pages => {
        expect(pages == null || pages > 0).toBeTrue();
    });
});

Run your rules with:

npm test

Breaking the Rules

If for some reason you need to disable some rule, use a skip comment with the rule names.

    - title: "a fantastic tale no 1" # skip(capitalized,letters-only)

For rules applying to the whole document, the skip comment must be on the first line:

# skip(schema,filename)
text: Hello

Expectations

Rulya uses Jasmine under the hood, you can use all its matchers in the rule definitions.

API

| | | |-|-| | documents(pattern,callback) | Traverses and parses YAML documents using a glob pattern. | | property(name,value,callback) | Steps down in a property to group multiple rules together. It creates a describe section at the Jasmine level. name and value typically corresponds to a YAML map entry. callback will be called with value as parameter or each item if value is an array. | | rule(name,value,description,callback) | Defines a rule. name identifies the rule if you want to skip it (see Breaking the Rules, above). value is the YAML element the rule applies to. This creates a single spec at the Jasmine level. | | schema(reference, doc) | Validates a document against a JSON Schema. reference is the filesystem path or an URL pointing to the schema. | ||

Customization

You can use Jasmine's describe and it functions if you need more flexibility than property and rule provide. Just note that rule manages the skip comment for you.