# JSON validation

By default, Modélico does not validate JSON in any special way. Moreover, the JSON is coerced when the metadata defined doesn't match the actual value, eg. if a field has `string()` as its metadata, but there is a number in the incoming JSON, it will be coerced with `String(5)`.

To validate the JSON strictly, you have the following options:

* use `M.ajvMetadata` for [Ajv](https://epoberezkin.github.io/ajv/)'s implementation of [JSON schema](http://json-schema.org/);
* manually create validation functions that work as revivers;
* a bit of both;
* alternatively, you can also override the reviver with your own.

## `M.ajvMetadata` and JSON schema

This variation of `M.metadata()` takes an optional `Ajv` instance parameter and returns metadata functions that take an additional parameter in the form of JSON schema for the current field. When no instance of `Ajv` is passed in, it returns metadata functions with the same API but no validation is performed. This can be leveraged to only enable validation during development in favour of faster parsing in production:

```javascript
import Ajv from 'ajv'

const ajvOptions = {}
const ajvIfProd = (ENV === 'development') ? Ajv(ajvOptions) : undefined
const {string, list, number} = M.ajvMetadata(ajvIfProd)

class Animal extends M.Base {
  static innerTypes() {
    return Object.freeze({
      name: string({minLength: 1, maxLength: 25}),
      dimensions: list(
        number({exclusiveMinimum: 0}),
        {minItems: 3, maxItems: 3}
      )
    })
  }
}
```

*Note: if you are using Modélico in the browser, you need to load Ajv as it is not bundled with Modélico.* [*See instructions here*](https://epoberezkin.github.io/ajv/#using-in-browser)*.*

## Custom validation metadata

If you only need to validate certain fields or you have custom rules that are not covered by what JSON schema can validate, you may write your own metadata. `M.withValidation` facilitates this use case.

```javascript
const {string, list, number} = M.metadata()

// lowerCaseString is going to return metadata that validates the string
// before reviving it by overriding the string metadata reviver
const lowerCaseString = () => M.withValidation(
  v => v.toLowerCase() === v,
  (v, path) => `string ${v} at ${path.join(' > ')} is not all lower case`
)(string())

class Animal extends M.Base {
  static innerTypes () {
    return Object.freeze({
      name: lowerCaseString(),
      dimensions: list(number())
    })
  }
}
```

## Why not both?

In the example above, we could have based `lowerCaseString` on the `ajvMetadata`-`string` instead of the normal `string` to combine custom and JSON schema rules.

`M.withValidation` works with any metadata, including the `Ajv` variant and can be composed, since it returns a function that takes metadata and returns metadata.

The error message function gets the path where the metadata is used to help debugging complex deep objects.

```javascript
const noNumbers = M.withValidation(
  v => /^[^0-9]*$/.test(v),
  (v, path) => `string ${v} at "${path.join(' > ')}" contains numbers`
)

const lowercase = M.withValidation(
  v => v.toLowerCase() === v,
  (v, path) => `string ${v} at "${path.join(' > ')}" is not all lower case`
)

const stringWithoutNumbersAndLowerCase = M.util.pipe(
  string,
  noNumbers,
  lowercase
)
```

Now we can define fields with something like `stringWithoutNumbersAndLowerCase({minLength: 5})`.

Please note that although it might be tempting to compose the validation functions and use `M.withValidation` only once with the result, by using `M.withValidation` for each individual function you can attach specific error messages to simplify debugging.

## Overriding the reviver

If you need to validate the JSON in a way not covered by the examples above, you may override the reviver with your own. This might be needed if the validity of some fields depends on other fields. In the following example, we make sure that `min <= max` in a `Range` class:

```javascript
const {base} = M.metadata()

const customReviver = baseReviver => (k, v, path = []) => {
  if (k !== '') {
    return v
  }

  if (v.min > v.max) {
    throw RangeError('"min" must be less than or equal to "max"')
  }

  return baseReviver(k, v, path)
}

class Range extends M.Base {
  constructor ({min = -Infinity, max = Infinity} = {}) {
    super({min, max})
  }

  length () {
    return this.max() - this.min()
  }

  static innerTypes () {
    return Object.freeze({
      min: number(),
      max: number()
    })
  }

  static metadata () {
    const baseMetadata = base(Range)
    const baseReviver = baseMetadata.reviver

    return Object.assign({}, baseMetadata, {reviver: customReviver(baseReviver) })
  }
}
```

In the class above, the validation could happen in the constructor. Although that would ensure direct use of the class or creation of new instances via `set` are also valid, it is sometimes preferable to consider internal use of the class as trusted and only validate external JSON.

One-off validations can be performed with `M.validate`, which takes a Modélico instance, optional inner metadata for generic types, and returns an array with 2 items: the result of the validation (boolean), and an `Error` if the validation was not successful.

Using the class:

```javascript
M.fromJS(Range, {min: 4, max: 3.5})
// => RangeError: "min" must be less than or equal to "max"

const myRange = new Range({min: 4, max: 3.5})
// => No error, but...

M.validate(myRange)
// => [false, RangeError("min" must be less than or equal to "max")]

const myRange2 = new Range({min: 4, max: 6.5})

M.validate(myRange2)
// => [true, undefined]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://modelico.javiercejudo.com/advanced/json_validation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.