Metadata-Version: 2.1
Name: simple-schema-validator
Version: 0.0.6
Summary: A dead-simple utility that validates if object has a certain structure.
Home-page: https://github.com/HackSoftware/simple_schema_validator
Author: Radoslav Georgiev
Author-email: radorado@hacksoft.io
License: MIT
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown


# Simple schema validator

A dead-simple utility that validates if object has a certain structure. Used in some of our projects.

## Basic usage

```
pip install simple_schema_validator
```

An example:

Lets say we have an API that returns the following data:

```json
{
  "user": 1,
  "profile": {
    "email": "some@user.com",
    "name": "Some User",
    "age": 20
  },
  "tokens": {
    "jwt": "...",
    "refresh": "...",
    "firebase": "...",
  }
}
```

And we are writing a simple integration test, that wants to assure the response has a certain structure.

Then we can use the schema validator like so:

```python
from simple_schema_validator import schema_validator

data = get_data_from_api()

schema = {
  'user': Any,
  'profile': {
    'email': Any,
    'name': Any,
    'age': Any
  },
  'tokens': {
    'jwt': Any,
    'refresh': Any,
    'firebase': Any
  }
}

result = schema_validator(schema, data)

if not result:
    print(f'Schema not valid. Missing: {result.missing_keys}, additional: {result.additional_keys}')
```

* `missing_keys` are those keys that are required in the `schema`, but not found in `data`.
* `additional_keys` are those keys present in `data`, but not required by the `schema`.
* Nested keys are represented with "dot" notation - `profile.email`, `tokens.jwt`, etc.

## Type checking

The util supports simple schema type checking.

Currently, the supported types in the schema are:

* `Any`
* `int`
* `float`
* `str`
* `bool`

If the type is `Any`, no type checking is done.

If there's a type mismatch, the errors are placed in the `type_errors` attribute of the result, which is a list of type errors.

The general format of a single type error is:

```python
{
  'path': 'the.path.to.the.value.in.data',
  'expected': the_expected_type_as_defined_in_the_schema,
  'actual': the_actual_type_of_the_value
}
```

Here's an example:


```python
from simple_schema_validator import schema_validator, types


schema = {
  'user': str,
  'profile': {
    'email': str,
    'name': str,
    'age': int
  },
  'tokens': {
    'jwt': str,
    'refresh': str,
    'firebase': str
  }
}

data = {
  'user': 'Some User',
  'profile': {
    'email': 'someuser@hacksoft.io',
    'name': 'Some User',
    'age': "29"
  },
  'tokens': {
    'jwt': 'some token value',
    'refresh': 'some token value',
    'firebase': 'some token value'
  }

}

result = schema_validator(schema, data)


assert bool(result) is False
assert result.type_errors == [{'path': 'profile.age', 'expected': int, 'actual': str}]
```

### Optional types

The schema validator support optional types.

You can do the following:

```python
from simple_schema_validator import schema_validator, types

schema = {
  'a': types.Optional[int]
}

data_1 = {
  'a': None
}

data_2 = {
  'a': 1
}

data_3 = {
  'a': 'some_string'
}

assert bool(schema_validator(schema, data_1)) is True
assert bool(schema_validator(schema, data_2)) is True
assert bool(schema_validator(schema, data_3)) is False
```

Additionally, you can define optional branches in the schema:

```python
from simple_schema_validator import schema_validator, types

schema = {
  'a': types.Optional[{
    'b': int
  }]
}

data_1 = {
  'a': None
}

data_2 = {
  'a': 1
}

data_3 = {
  'a': {
    'b': 1
  }
}

data_4 = {
  'a': {
    'b': 'some_string'
  }
}

assert bool(schema_validator(schema, data_1)) is True
assert bool(schema_validator(schema, data_2)) is False
assert bool(schema_validator(schema, data_3)) is True
assert bool(schema_validator(schema, data_4)) is False
```


