json-schema-matcher 0.1.7.1
Use this Lib to create a structure schema of a given JSON and also to check if a given JSON matches a given schema.
License: MIT
Keywords: json schema diff differ comparison

JSON Differ and Schema Matcher
==============================

Use this Lib to create a structure schema of a given JSON and also to check if a given JSON matches a given schema or simply to diff 2 JSONs.


Why Should I Use This?
----------------------

I made this for use when validating a JSON REST API using Behave. I wanted to be sure that the JSON's structure is correct, no matter it's content.

You may use it for whatever you want :)


Differ Features
---------------

- Diff 2 JSONs


Schema Features
---------------

- Export schema for a given JSON
- Validate a given schema
- Check if a given JSON matches a given schema
- Highlight any unmatched data between JSON and schema



Differ Usage
------------

diff_jsons()
""""""""""""
Show differences between 2 JSONs
::

    In [1]: from json_schema.json_differ import diff_jsons

    In [2]: diff_jsons('{"a": "1"}', '{"a": 2}')
    {
        "a": "'2' should match 'str:1'"
    }
    Out[2]: False

    In [3]: diff_jsons('{"a": "1"}', '{"a": "1"}')
    Out[3]: True


Schema Usage
------------

json_schema.loads()
"""""""""""""""""""
Load schema function. Receive a schema and return and JsonSchema object instance.
::

    In [1]: from json_schema import json_schema

    In [2]: my_schema = '{"my_key": "int:0:10|str"}'

    In [3]: my_schema_object = json_schema.loads(my_schema)

    In [4]: my_schema_object
    Out[4]: <json_schema.JsonSchema at 0x10aa96f10>

json_schema.dumps()
"""""""""""""""""""
Dump schema function. Receive a JSON and return an automaticaly created schema. Its very userful when working with some large or complex JSON. Be aware that you may have to adapt its returned schema to work with your JSON variations. For example, if your JSON have some optional value that, this time, is null the schema created will expect that that value is AWAYS null.
:: 

    In [1]: from json_schema import json_schema

    In [2]: my_json = '{"parrot": ["is no more", "It has ceased to be"], "ex-parrot": true, "volts": 2000}'

    In [3]: my_automatic_schema = json_schema.dumps(my_json)

    In [4]: my_automatic_schema
    Out[4]: '{"ex-parrot": "bool", "parrot": ["str", "..."], "volts": "int"}'


json_schema.match()
"""""""""""""""""""
Check if a given JSON matches a given schema.
::

    In [1]: from json_schema import json_schema

    In [2]: my_json = '{"parrot": ["is no more", "It has ceased to be"], "ex-parrot": true, "volts": 2000}'

    In [3]: my_schema = '{"ex-parrot": "bool", "parrot": ["str", "..."], "volts": "int"}'

    In [4]: json_schema.match(my_json, my_schema)
    Out[4]: True


JsonSchema Object
"""""""""""""""""
Object that contains all validations e checkups for that given schema.

JsonSchema.full_check()
"""""""""""""""""""""""
Check and highlights any errors found.
::

    In [1]: from json_schema import json_schema

    In [2]: my_schema = '{"ex-parrot": "bool", "parrot": ["str", "..."], "volts": "int"}'

    In [3]: JS = json_schema.loads(my_schema)

    In [4]: my_json = '{"parrot": ["is no more", "It has ceased to be"], "ex-parrot": true, "volts": 2000}'

    In [5]: JS.full_check(my_json)
    {
        "ex-parrot": true, 
        "parrot": [
            true, 
            true
        ], 
        "volts": true
    }

    In [6]: other_json = '{"parrot": ["is no more", "It has ceased to be"], "ex-parrot": true, "volts": "foobar"}'

    In [7]: JS.full_check(other_json)
    {
        "ex-parrot": true, 
        "parrot": [
            true, 
            true
        ], 
        "volts": "'foobar' should match 'int'"
    }


Usage Example
-------------

::

    In [1]: from json_schema import json_schema

    In [2]: um_json = '''{"chave_list": [1, 2],
                          "chave_dict": {"chave": "valor"},
                          "chave_int": 1,
                          "chave_float": 1.2,
                          "chave_string": "1"}'''

    In [3]: esquema = json_schema.dumps(um_json)

    In [4]: print esquema
    {"chave_list": ["int", "..."], "chave_dict": {"chave": "str"}, "chave_int": "int", "chave_float": "float", "chave_string": "str"}

    In [5]: js = json_schema.loads(esquema)

    In [6]: js
    Out[6]: <json_schema.JsonSchema at 0x1064f0f50>

    In [7]: js == um_json
    Out[7]: True


Validators
----------

string
""""""

Will match only if that given JSON data is string.

::

    '{"my_key": "str"}'

Will match any of those:
::

    '{"my_key": "my_value"}'
    '{"my_key": "my value"}'
    '{"my_key": ""}'
    '{"my_key": "123"}'
    '{"my_key": "3.567"}'

It my have max length limit using "str:max_len"

::

    '{"my_key": "str:3"}'

Will match any of those:
::

    '{"my_key": ""}'
    '{"my_key": "a"}'
    '{"my_key": "ab"}'
    '{"my_key": "abc"}'
    '{"my_key": "123"}'

But not match those:
::

    '{"my_key": "abcd"}'
    '{"my_key": "abcde"}'
    '{"my_key": "1234"}'

Or direct string match using "str:string_to_match"

::

    '{"my_key": "str:Foo Bar"}'

Will match only:
::

    '{"my_key": "Foo Bar"}'

And not match those:
::

    '{"my_key": "foo bar"}'
    '{"my_key": "Foo bar"}'
    '{"my_key": "anything else"}'

int
"""

Will match only if that given JSON data is integer.

::

    '{"my_key": "int"}'

Will match any of those:
::

    '{"my_key": 0}'
    '{"my_key": 1}'
    '{"my_key": 12345}'
    '{"my_key": -1}'
    '{"my_key": -123}'

It my have min:max value limit using "int:min:max"

::

    '{"my_key": "int:-3:3"}'

Will match any of those:
::

    '{"my_key": 0}'
    '{"my_key": -1}'
    '{"my_key": -3}'
    '{"my_key": 1}'
    '{"my_key": 3}'

But not match those:
::

    '{"my_key": -4}'
    '{"my_key": 4}'
    '{"my_key": 12345}'


float
"""""

Same as int but for float values
::

    '{"my_key": "float"}'

Will match any of those:
::

    '{"my_key": 0.0}'
    '{"my_key": 1.1}'
    '{"my_key": 123.45}'
    '{"my_key": -1.1}'
    '{"my_key": -12.3}'

It my have min:max value limit using "float:min:max"

::

    '{"my_key": "float:-3.1:3.5"}'

Will match any of those:
::

    '{"my_key": 0.0}'
    '{"my_key": -1.2}'
    '{"my_key": -3.1}'
    '{"my_key": 1.0}'
    '{"my_key": 3.5}'

But not match those:
::

    '{"my_key": -4.0}'
    '{"my_key": 4.0}'
    '{"my_key": 123.45}'
    '{"my_key": 2}'


url
"""

Will match only if that given JSON data is a string that contains a valid URL.

::

    '{"my_key": "url"}'

Will match any of those:
::

    '{"my_key": "http://example.com"}'
    '{"my_key": "https://example.com"}'
    '{"my_key": "ftp://example.com"}'
    '{"my_key": "ftps://example.com"}'

Validation is made using the folowing python regular expression code
::

    regex = re.compile(r'^(?:http|ftp)s?://'  # HTTP, HTTPS, FTP, FTPS
                       # Dominio
                       r'(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+(?:[A-Z]{2,6}\.?|[A-Z0-9-]{2,}\.?)|'
                       # Localhost
                       r'localhost|'
                       # IP
                       r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})'
                       # Porta
                       r'(?::\d+)?'
                       r'(?:/?|[/?]\S+)$', re.IGNORECASE)
    return True if regex.match(item) else False


bool
""""

Will match only if that given JSON data is boolean.

::

    '{"my_key": "bool"}'

Will match only:
::

    '{"my_key": true}'
    '{"my_key": false}'

You may also match it's value:
::

    '{"my_key": "bool:True"}'
    '{"my_key": "bool:False"}'


regex
"""""

Will match only if that given JSON data is string and match some regex string.

::

    '{"my_key": "regex:[regex string]"}'

Example:
::

    In [1]: from json_schema import json_schema

    In [2]: json_schema.loads('{"my_key": "regex:^[0-9]{2}:[0-9]{2}:[0-9]{2}"}') == '{"my_key": "00:00:00"}'
    Out[2]: True

    In [3]: json_schema.loads('{"my_key": "regex:^[0-9]{2}:[0-9]{2}:[0-9]{2}"}') == '{"my_key": "00:00:0"}'
    Out[3]: False

    In [4]: json_schema.loads('{"my_key": "regex:^[0-9]{2}:[0-9]{2}:[0-9]{2}"}') == '{"my_key": "00:00:AA"}'
    Out[4]: False


python
""""""

Will match only if that given python code return True.
The value in JSON will be used as 'value' variable.

::

    '{"my_key": "python:[python code]"}'

Example:
::

    In [1]: from json_schema import json_schema

    In [2]: json_schema.loads('{"my_key": "python:value.upper() == value"}') == '{"my_key": "FOOBAR"}'
    Out[2]: True

    In [3]: json_schema.loads('{"my_key": "python:value.upper() == value"}') == '{"my_key": "FooBar"}'
    Out[3]: False

    In [4]: json_schema.loads('{"my_key": "python:value%2 == 2"}') == '{"my_key": 10}'
    Out[4]: True

    In [5]: json_schema.loads('{"my_key": "python:value%2 == 2"}') == '{"my_key": 11}'
    Out[5]: False


datetime
""""""""

Will match only if that given value match with datetime string formatter
https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior

::

    '{"my_key": "datetime:format string"}'

Example:
::

    In [1]: from json_schema import json_schema

    In [2]: json_schema.loads('{"my_key": "datetime:%Y-%m-%d"}') == '{"my_key": "2015-07-07"}'
    Out[2]: True

    In [3]: json_schema.loads('{"my_key": "datetime:%Y-%m-%d"}') == '{"my_key": "2015-17-07"}'
    Out[3]: False

    In [4]: json_schema.loads('{"my_key": "datetime:%d/%m/%Y %H:%M:%S"}') == '{"my_key": "13/04/1984 11:22:33"}'
    Out[4]: True

    In [5]: json_schema.loads('{"my_key": "datetime:%d/%m/%Y %H:%M:%S"}') == '{"my_key": "04/13/1984 11:22:33"}'
    Out[5]: False



any
"""

Will match anything but null.

::

    '{"my_key": "any"}'

Will match any of those:
::

    '{"my_key": 10}'
    '{"my_key": "foo"}'
    '{"my_key": 1.5}'
    '{"my_key": true}'
    '{"my_key": ""}'

But not

::

    '{"my_key": null}'

null
""""

Will match only null values.

::

    '{"my_key": "null"}'

Will match:
::

    '{"my_key": null}'

But not
::

    '{"my_key": 10}'
    '{"my_key": "foo"}'
    '{"my_key": 1.5}'
    '{"my_key": true}'
    '{"my_key": ""}'

empty
"""""

Will match empty structures.

Supported:
::

    '{"my_key": "empty:list"}'
    '{"my_key": "empty:dict"}'
    '{"my_key": "empty:hash"}'
    '{"my_key": "empty:object"}'

Types 'hash', 'dict' and 'object' are actually same

::

    '{"my_key": "empty:list"}'


Will match:
::

    '{"my_key": []}'

And
::

    '{"my_key": "empty:object"}'


Will match:
::

    '{"my_key": {}}'


But not

::

    '{"my_key": null}'


Especial validations
--------------------

'|' - OR operator
"""""""""""""""""

Will match if any of validators match.
::

    '{"my_key": "str|int"}'

Will match:
::

    '{"my_key": "foo"}'
    '{"my_key": 123}'

Example
::

    In [1]: from json_schema import json_schema

    In [2]: json_schema.loads('{"my_key": "int|str"}') == '{"my_key": "foo"}'
    Out[2]: True

    In [3]: json_schema.loads('{"my_key": "int|str"}') == '{"my_key": 123}'
    Out[3]: True

    In [4]: json_schema.loads('{"my_key": "int:0:10|str:3"}') == '{"my_key": "foo"}'
    Out[4]: True

    In [5]: json_schema.loads('{"my_key": "int:0:10|str:3"}') == '{"my_key": 3}'
    Out[5]: True

    In [6]: json_schema.loads('{"my_key": "int:0:10|str:2"}') == '{"my_key": "foo"}'
    Out[6]: False

    In [7]: json_schema.loads('{"my_key": "int:10|str"}') == '{"my_key": 123}'
    Out[7]: False


This will match everything:
::

    '{"my_key": "any|null"}'


Arrays
""""""

Arrays are ordered so your schema order matters as also its size.
::

    '{"my_key": ["str", "str", "int"]}'

Will match:
::

    '{"my_key": ["foo", "bar", 123]}'

But not
::

    '{"my_key": ["foo", 123, "bar"]}'
    '{"my_key": ["foo", "bar", 123, 123]}'

If you dont know the size of your array you may user a special 2 item arrays as follows
::

    '{"my_key": ["str", "..."]}'

That will match:
::

    '{"my_key": ["foo"]}'
    '{"my_key": ["foo", "bar"]}'
    '{"my_key": ["foo", "bar", "Hello World"]}'
    '{"my_key": ["foo", "bar", "Hello World", "etc"]}'

Or even:
::

    '{"my_key": ["str|int", "..."]}'

That will match:
::

    '{"my_key": ["foo"]}'
    '{"my_key": [123]}'
    '{"my_key": ["foo", "bar"]}'
    '{"my_key": ["foo", 123, "Hello World"]}'
    '{"my_key": [123, "bar", "Hello World", 0]}'


Hashs (dicts)
"""""""""""""

Hashs are not ordered so your schema order does not matters but its keys does.
::

    '{"my_key": {"internal_key_1": "str", "internal_key_2": "int"}'

Will match:
::

    '{"my_key": {"internal_key_1": "foo", "internal_key_2": 123}'
    '{"my_key": {"internal_key_2": 123, "internal_key_2": "foo"}'

But not
::

    '{"my_key": {"internal_key_1": 123, "internal_key_2": "foo"}'
    '{"my_key": {"internal_key_1": "foo", "internal_key_3": 123}'
    '{"my_key": {"internal_key_1": "foo", "internal_key_2": 123, "fizz": "buzz"}'


Recursivity
"""""""""""

All validations are recursive so they will check into arrays, hashs, array of arrays, etc.
::

    '[{"my_key": ["str|int", "..."]}, {"my_key": "str"}, "int", ["int|str", "str"]'

Will match:
::

    '[{"my_key": [1, "foo", "bar", 100]}, {"my_key": "foo"}, 12345, [123, "foo"]'