# jsonschema
Haskell library for deriving and validating JSON Schema (2020-12).
This library provides:
- Automatic JSON Schema derivation from Haskell types via `GHC.Generics`.
- Sensible encodings for records, products, and sum types (with tags).
- `$defs`/`$ref` support for recursive types.
- A validator that implements the core 2020-12 validation + applicator vocabularies.
- Helpful error reporting with instance paths when you want detailed feedback.
- High-level API exposed through `Data.JSON.JSONSchema` (re-exporting `ToJSONSchema` and helpers).
## Features
- Derive schemas with the `ToJSONSchema` type class; generic default handles most ADTs.
- Records become JSON objects with named properties, emit `"required"` for every field, and forbid extras via `additionalProperties: false`. Non-record products become arrays with `prefixItems` and `items: false`.
- Sum types are modeled with discriminator tags:
- Record constructors: object with a required `tag` (constructor name) and the record fields.
- Non-record constructors: object `{ tag, contents }`, both required, where `contents` carries the constructor’s payload (array/object).
- Recursive types are emitted under `"$defs"` and referenced with `"$ref"`.
- Validation covers: `type`, `const`, `enum`, numeric and string constraints, arrays (`prefixItems`, `items`, `contains`, `minContains`, `maxContains`), objects (`properties`, `patternProperties`, `additionalProperties`, `propertyNames`, `required`, `dependentSchemas`, `dependentRequired`), combinators (`anyOf`, `oneOf`, `allOf`, `not`), conditionals (`if`/`then`/`else`), and pragmatic `unevaluated*`.
- Local `$ref` resolution using JSON Pointers within the same document.
Notes and limits:
- JSON Schema version: 2020-12. `format` and `content*` are treated as annotations (not asserted).
- `$ref` resolution is local (`#...`) only; external URIs/anchors are not resolved.
- `unevaluatedProperties`/`unevaluatedItems` are implemented with a practical, local approximation.
## Quick Start
Add the library to your build, then import the high-level module:
```haskell
import GHC.Generics (Generic)
import Data.Aeson (ToJSON, Value, object, (.=))
import Data.Proxy (Proxy(..))
import Data.Text (Text)
import Data.JSON.JSONSchema -- ToJSONSchema(..), Proxy(..), validateJSONSchema
import JSONSchema.Validation -- validate / validateWithErrors (optional)
```
### 1) Derive a schema for your type
```haskell
data Person = Person
{ name :: Text
, age :: Int
} deriving (Show, Eq, Generic)
instance ToJSON Person
instance ToJSONSchema Person
-- Produce the JSON Schema (as an Aeson Value)
personSchema :: Value
personSchema = toJSONSchema (Proxy :: Proxy Person)
```
What you get (shape, simplified):
```jsonc
{
"$defs": {
"Person": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"}
},
"additionalProperties": false,
"required": ["name", "age"]
}
},
"$ref": "#/$defs/Person"
}
```
Sum types are tagged. For example:
```haskell
data Shape
= Circle Double
| Rectangle Double Double
deriving (Show, Eq, Generic)
instance ToJSON Shape
instance ToJSONSchema Shape
shapeSchema :: Value
shapeSchema = toJSONSchema (Proxy :: Proxy Shape)
```
Non-record constructors encode as objects like `{ tag: { const: "Circle" }, contents: <payload> }`.
Record constructors encode as objects with a `tag` plus their named fields.
### 2) Validate data against a schema
Use the simple boolean check:
```haskell
import Data.Aeson (toJSON)
valid :: Bool
valid = validateJSONSchema personSchema (toJSON (Person "Alice" 30))
```
Or collect all validation errors:
```haskell
import JSONSchema.Validation (validate, validateWithErrors, ValidationError(..))
case validate personSchema (toJSON (Person "Alice" 30)) of
Right () -> putStrLn "OK"
Left errs -> mapM_ print errs -- includes JSON Pointer-like paths
```
You can validate any `Value` against any schema, including hand-written schemas:
```haskell
let schema = object
[ "type" .= ("object" :: Text)
, "properties" .= object ["name" .= object ["type" .= ("string" :: Text)]]
, "required" .= (["name"] :: [Text])
]
in validateJSONSchema schema (object ["name" .= ("Bob" :: Text)])
```
### 3) Custom schemas for special types
Provide an explicit instance when you need a specific schema shape:
```haskell
newtype UUID = UUID Text
instance ToJSONSchema UUID where
toJSONSchema _ = object
[ "type" .= ("string" :: Text)
, "minLength" .= (36 :: Int)
, "maxLength" .= (36 :: Int)
]
```
## Tips
- Pretty-print schemas with `aeson-pretty` if you want human-friendly output.
- For `Maybe a`, the schema is `anyOf [schema(a), {"type":"null"}]`.
- For `[a]`, the schema is `{ "type": "array", "items": schema(a) }`.
- For `Either a b`, the schema is `anyOf` with `{ "Left": a }` and `{ "Right": b }` object encodings.
## Development
- Build and test with Cabal:
- `cabal build`
- `cabal test`
## License
Released under the Mozilla Public License 2.0 by DPella AB. See `LICENSE` for details.