README.md

Eskema is a tool to help you validate dynamic data with a simple yet powerful API.

It was initially intended to validate dynamic JSON returned from an API, passed in by a user or any other scenario where you might need to validate dynamic data. But it's not limited to JSON data, you can validate any type of dinamic data.

Features

• Simple API
• Composable / Extensible
• Safe
• Fully tested

Getting started

To use the package there's not much to do apart from installing the package or adding it to pubspec.yml. For a guide on how to do it, check the install instructions

Concepts

Validator

Mostly everything in Eskema are [Validators], which are functions that take in a value and return a [IResult].

The following are all validators:

isType<String>();
listOfLength(2);
listEach(isType<String>());
all([isType<List>(), isListOfLength(2)]);

IResult

This is a class that represents the result of a validation

Usage

An example explains more than 100 words, so here are a couple of simple examples. For more detailed examples check the /examples folder.

Simple example

NOTE: that if you only want to validate a single value, you probably don't need Eskema.

Otherwise let's check how to validate a single value. You can use validators individually:

final isString = isType<String>();
const result1 = isString('valid string');
const result2 = isString(123);

result1.isValid;  // true
result2.isValid;  // false
result2.expected; // String

Or you can combine validators:

all([isType<String>(), isDate()]);     // all validators must be valid
or(isType<String>(), isType<int>());   // either validator must be valid
and(isType<String>(), isType<int>());  // both validator must be valid


// This validator checks that, the value is a list of strings, with length 2, and contains item "test"
all([
  isOfLength(2),                    // checks that the list is of length 2
  listEach(isTypeOrNull<String>()), // checks that each item is either string or null
  listContains('test'),             // list must contain value "test"
]);

// This validator checks a map against a eskema. Map must contain property 'books', 
// which is a list of maps that matches a sub-eskema. Subeskema validates that the map has a name which is a string
final matchesEskema = eskema({
  'books': listEach(
    eskema({
      'name': isType<String>(),
    }),
  ),
});
matchesEskema({'books': [{'name': 'book name'}]});

Validators

isType

This validator checks that a value is of a certain type

isType<String>();
isType<int>();
isType<double>();
isType<List>();
isType<Map>();

isTypeOrNull

This validator checks that a value is of a certain type or is null

isTypeOrNull<String>();
isTypeOrNull<int>();

nullable

This validator allows to make validators allow null values

nullable(eskema({...}));

• The validator above, allows a map or null

eskema

The most common use case will probably be validating JSON or dynamic maps. For this, you can use the eskema validator.

In this example we validate a Map with optional fields and with nested fields.

final validateMap = eskema({
  'name': isTypeString(),
  'address': nullable(
    eskema({
      'city': isTypeString(),
      'street': isTypeString(),
      'number': all([
        isTypeInt(),
        isMin(0),
      ]),
      'additional': nullable(
        eskema({
          'doorbel_number': Field([isTypeInt()])
        })
      ),
    })
  )
});

final invalidResult = validateMap.call({});
invalidResult.isValid;    // false
invalidResult.isNotValid; // true
invalidResult.expected;   // name -> String
invalidResult.message;    // Expected name -> String

final validResult = validateMap.call({ 'name': 'bobby' });
validResult.isValid;    // true
validResult.isNotValid; // false
validResult.expected;   // Valid

listEach

The other common use case is validating dynamic Lists. For this, you can use the listEach class.

This example validates that the provided value is a List of length 2, and each item must be of type int:

final isValidList = all([
    listOfLength(2),
    listEach(isTypeInt()),
]);

isValidList.validate(null).isValid;      // true
isValidList.validate([]).isValid;        // true
isValidList.validate([1, 2]).isValid;    // true
isValidList.validate([1, "2"]).isValid;  // false
isValidList.validate([1, "2"]).expected; // [1] -> int

Additional Validators

For a complete list of validators, check the docs

Custom Validators

Eskema offers a set of common Validators located in lib/src/validators.dart. You are not limited to only using these validators, custom ones can be created very easily.

Let's see how to create a validator to check if a string matches a pattern:

Validator validateRegexp(RegExp regexp) {
  return (value) {
    return Result(
      isValid: regexp.hasMatch(value),  
      expected: 'match pattern $regexp', // the message explaining what this validator expected
    );
  };
}

If you want a validator you built to be part of the package, please send in a PR and I will consider adding it!!

More examples

For more examples check out the /examples folder. Or check out the docs

Package Name

Eskema is the Vasque word for "Schema". I did not know what to call the package, and after looking for a bit I found the Vasque word for schema and decided to use it!

Additional information

• For more information check the docs out.
• If you find a bug please file an issue or send a PR my way.
• Contributions are welcomed, feel free to send in fixes, new features, custom validators, etc...