package ppx_deriving_jsonschema
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=53ef084d01e8b21b495a0fa068a11acd0bc3b435028d302396660f6ee69685a6
sha512=d09890057505e8ab6b5a997717d524a514666b467cfe40f37a29a3189056bf32527cd66827c65dc847eeefba36b04e1143ec320080848df20f8adf01e748d8a3
Description
ppx_deriving_jsonschema is a ppx rewriter that generates jsonschema from ocaml types
README
ppx_deriving_jsonschema
ppx_deriving_jsonschema
is a PPX syntax extension that generates JSON schema from OCaml types.
The conversion aims to be compatible with the existing json derivers.
Installation
opam install ppx_deriving_jsonschema
[@@deriving jsonschema]
type address = {
street: string;
city: string;
zip: string;
} [@@deriving jsonschema]
type t = {
name: string;
age: int;
email: string option;
address: address;
} [@@deriving jsonschema]
let schema = Ppx_deriving_jsonschema_runtime.json_schema t_jsonschema
Such a type will be turned into a JSON schema like this:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"zip": { "type": "string" },
"city": { "type": "string" },
"street": { "type": "string" }
},
"required": [ "zip", "city", "street" ]
},
"email": { "type": "string" },
"age": { "type": "integer" },
"name": { "type": "string" }
},
"required": [ "address", "age", "name" ]
}
Conversion rules
Basic types
Types int
, int32
, int64
, string
, float
, bool
are converted to their JSON equivalents.
Type char
is converted to { "type": "string", "minLength": 1, "maxLength": 1}
.
List and arrays
OCaml lists and arrays are converted to { "type": "array", "items": { "type": "..." } }
.
Tuples
Tuples are converted to { "type": "array", "items": [...] }
.
Variants and polymorphic variants
Variants are converted to { "type": "string", "enum": [...] }
.
if the JSON variant names differ from OCaml conventions, users can specify the corresponding JSON string explicitly using [@name "constr"]
, for example:
type t =
| Typ [@name "type"]
| Class [@name "class"]
[@@deriving jsonschema]
Records
Records are converted to { "type": "object", "properties": {...}, "required": [...] }
.
The fields of type option
are not included in the required
list.
When the JSON object keys differ from the ocaml field names, users can specify the corresponding JSON key implicitly using [@key "field"]
, for example:
type t = {
typ : float [@key "type"];
class_ : float [@key "CLASS"];
}
[@@deriving jsonschema]
References
Rather than inlining the definition of a type it is possible to use a json schema $ref
using the [@ref "name"]
attribute. In such a case, the type definition must be passed to Ppx_deriving_jsonschema_runtime.json_schema
as a parameter.
type address = {
street : string;
city : string;
zip : string;
}
[@@deriving jsonschema]
type t = {
name : string;
age : int;
email : string option;
home_address : address; [@ref "shared_address"]
work_address : address; [@ref "shared_address"]
retreat_address : address; [@ref "shared_address"]
}
[@@deriving jsonschema]
let schema =
Ppx_deriving_jsonschema_runtime.json_schema
~definitions:[("shared_address", address_jsonschema)]
t_jsonschema
Would produce the following schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"shared_address": {
"type": "object",
"properties": {
"zip": { "type": "string" },
"city": { "type": "string" },
"street": { "type": "string" }
},
"required": [ "zip", "city", "street" ]
}
},
"type": "object",
"properties": {
"retreat_address": { "$ref": "#/$defs/shared_address" },
"work_address": { "$ref": "#/$defs/shared_address" },
"home_address": { "$ref": "#/$defs/shared_address" },
"email": { "type": "string" },
"age": { "type": "integer" },
"name": { "type": "string" }
},
"required": [
"retreat_address", "work_address", "home_address", "age", "name"
]
}
Dev Dependencies (4)
-
odoc
with-doc
-
ocaml-lsp-server
with-dev-setup
-
ocamlformat
with-dev-setup
-
yojson
with-test
Used by
None
Conflicts
None