⬅ Back to highlights

ReScript Schema PPX

ReScript PPX to generate rescript-schema from type.

🧠 It's 100% opt-in. You can use rescript-schema without ppx.

Table of contents

• Table of contents
• Install
• Basic usage
• API reference

Install

1npm install rescript-schema rescript-schema-ppx

Then update your rescript.json config:

1{
2  ...
3+ "bs-dependencies": ["rescript-schema"],
4+ "bsc-flags": ["-open RescriptSchema"],
5+ "ppx-flags": ["rescript-schema-ppx/bin"],
6}

Basic usage

1// 1. Define a type and add @schema attribute
2@schema
3type rating =
4  | @as("G") GeneralAudiences
5  | @as("PG") ParentalGuidanceSuggested
6  | @as("PG13") ParentalStronglyCautioned
7  | @as("R") Restricted
8@schema
9type film = {
10  @as("Id")
11  id: float,
12  @as("Title")
13  title: string,
14  @as("Tags")
15  tags: @s.default([]) array<string>,
16  @as("Rating")
17  rating: rating,
18  @as("Age")
19  deprecatedAgeRestriction: @s.deprecate("Use rating instead") option<int>,
20}
21
22// 2. Generated by PPX ⬇️
23let ratingSchema = S.union([
24  S.literal(GeneralAudiences),
25  S.literal(ParentalGuidanceSuggested),
26  S.literal(ParentalStronglyCautioned),
27  S.literal(Restricted),
28])
29let filmSchema = S.object(s => {
30  id: s.field("Id", S.float),
31  title: s.field("Title", S.string),
32  tags: s.fieldOr("Tags", S.array(S.string), []),
33  rating: s.field("Rating", ratingSchema),
34  deprecatedAgeRestriction: s.field("Age", S.option(S.int)->S.deprecate("Use rating instead")),
35})
36
37// 3. Parse data using the schema
38// The data is validated and transformed to a convenient format
39%raw(`{
40  "Id": 1,
41  "Title": "My first film",
42  "Rating": "R",
43  "Age": 17
44}`)->S.parseOrThrow(filmSchema)
45// Ok({
46//   id: 1.,
47//   title: "My first film",
48//   tags: [],
49//   rating: Restricted,
50//   deprecatedAgeRestriction: Some(17),
51// })
52
53// 4. Transform data back using the same schema
54{
55  id: 2.,
56  tags: ["Loved"],
57  title: "Sad & sed",
58  rating: ParentalStronglyCautioned,
59  deprecatedAgeRestriction: None,
60}->S.reverseConvertOrThrow(filmSchema)
61// Ok(%raw(`{
62//   "Id": 2,
63//   "Title": "Sad & sed",
64//   "Rating": "PG13",
65//   "Tags": ["Loved"],
66//   "Age": undefined,
67// }`))
68
69// 5. Use schema as a building block for other tools
70// For example, create a JSON-schema with rescript-json-schema and use it for OpenAPI generation
71let filmJSONSchema = JSONSchema.make(filmSchema)

🧠 Read more about schema usage in the ReScript Schema for ReScript users documentation.

API reference

@schema

Applies to: type declarations, type signatures

Indicates that a schema should be generated for the given type.

@s.matches(S.t<'value>)

Applies to: type expressions

Specifies custom schema for the type.

1@schema
2type t = @s.matches(S.string->S.url) string
3
4// Generated by PPX ⬇️
5let schema = S.string->S.url

@s.null

Applies to: option type expressions

Tells to use S.null for the option schema constructor.

1@schema
2type t = @s.null option<string>
3
4// Generated by PPX ⬇️
5let schema = S.null(S.string)

@s.nullable

Applies to: option type expressions

Tells to use S.nullable for the option schema constructor.

1@schema
2type t = @s.nullable option<string>
3
4// Generated by PPX ⬇️
5let schema = S.nullable(S.string)

@s.default('value)

Applies to: type expressions

Wraps the type expression schema into an option with the provided default value.

1@schema
2type t = @s.default("Unknown") string
3
4// Generated by PPX ⬇️
5let schema = S.option(S.string)->S.Option.getOr("Unknown")

It might be used together with @s.null or @s.nullable:

1@schema
2type t = @s.nullable @s.default("Unknown") string
3
4// Generated by PPX ⬇️
5let schema = S.nullable(S.string)->S.Option.getOr("Unknown")

@s.defaultWith(unit => 'value)

Applies to: type expressions

Wraps the type expression schema into an option with callback to get the default value.

1@schema
2type t = @s.defaultWith(() => []) array<string>
3
4// Generated by PPX ⬇️
5let schema = S.option(S.array(S.string))->S.Option.getOrWith(() => [])

🧠 The same as @s.default it might be used together with @s.null or @s.nullable

@s.describe(string)

Applies to: type expressions

Adds description property to the generated schema.

1@schema
2type t = @s.describe("A useful bit of text, if you know what to do with it.") string
3
4// Generated by PPX ⬇️
5let schema = S.string->S.describe("A useful bit of text, if you know what to do with it.")

This can be useful for documenting a field, for example in a JSON Schema using a library like rescript-json-schema.

@s.deprecate(string)

Applies to: type expressions

Adds deprecation property to the generated schema.

1@schema
2type t = @s.deprecate("Will be removed in APIv2") string
3
4// Generated by PPX ⬇️
5let schema = S.string->S.deprecate("Will be removed in APIv2")

This can be useful for documenting a field, for example in a JSON Schema using a library like rescript-json-schema.