1 | <h1 align="center">Fastify</h1>
|
2 |
|
3 | ## Fluent Schema
|
4 |
|
5 | The [Validation and Serialization](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md) documentation outlines all parameters accepted by Fastify to set up JSON Schema Validation in order to validate the input, and JSON Schema Serialization in order to optimize the output.
|
6 |
|
7 | [`fluent-schema`](https://github.com/fastify/fluent-schema) can be used to simplify this task while allowing the reuse of constants.
|
8 |
|
9 | ### Basic settings
|
10 |
|
11 | ```js
|
12 | const S = require('fluent-schema')
|
13 |
|
14 | // You can have an object like this, or query a DB to get the values
|
15 | const MY_KEY = {
|
16 | KEY1: 'ONE',
|
17 | KEY2: 'TWO'
|
18 | }
|
19 |
|
20 | const bodyJsonSchema = S.object()
|
21 | .prop('someKey', S.string())
|
22 | .prop('someOtherKey', S.number())
|
23 | .prop('requiredKey', S.array().maxItems(3).items(S.integer()).required())
|
24 | .prop('nullableKey', S.mixed([S.TYPES.NUMBER, S.TYPES.NULL]))
|
25 | .prop('multipleTypesKey', S.mixed([S.TYPES.BOOLEAN, S.TYPES.NUMBER]))
|
26 | .prop('multipleRestrictedTypesKey', S.oneOf([S.string().maxLength(5), S.number().minimum(10)]))
|
27 | .prop('enumKey', S.enum(Object.values(MY_KEYS)))
|
28 | .prop('notTypeKey', S.not(S.array()))
|
29 |
|
30 | const queryStringJsonSchema = S.object()
|
31 | .prop('name', S.string())
|
32 | .prop('excitement', S.integer())
|
33 |
|
34 | const paramsJsonSchema = S.object()
|
35 | .prop('par1', S.string())
|
36 | .prop('par2', S.integer())
|
37 |
|
38 | const headersJsonSchema = S.object()
|
39 | .prop('x-foo', S.string().required())
|
40 |
|
41 | // Note that there is no need to call `.valueOf()`!
|
42 | const schema = {
|
43 | body: bodyJsonSchema,
|
44 | querystring: queryStringJsonSchema, // (or) query: queryStringJsonSchema
|
45 | params: paramsJsonSchema,
|
46 | headers: headersJsonSchema
|
47 | }
|
48 |
|
49 | fastify.post('/the/url', { schema }, handler)
|
50 | ```
|
51 |
|
52 | ### Reuse
|
53 |
|
54 | With `fluent-schema` you can manipulate your schemas in an easier and programmatic way and then reuse them
|
55 | thanks to the `addSchema()` method. You can refer to the schema in two different manners that are detailed
|
56 | in the [Validation-and-Serialization.md](./Validation-and-Serialization.md#adding-a-shared-schema) documentation.
|
57 |
|
58 | Here are some usage examples:
|
59 |
|
60 | **`$ref-way`**: refer to an external schema.
|
61 |
|
62 | ```js
|
63 | const addressSchema = S.object()
|
64 | .id('#address')
|
65 | .prop('line1').required()
|
66 | .prop('line2')
|
67 | .prop('country').required()
|
68 | .prop('city').required()
|
69 | .prop('zipcode').required()
|
70 |
|
71 | const commonSchemas = S.object()
|
72 | .id('https://fastify/demo')
|
73 | .definition('addressSchema', addressSchema)
|
74 | .definition('otherSchema', otherSchema) // You can add any schemas you need
|
75 |
|
76 | fastify.addSchema(commonSchemas)
|
77 |
|
78 | const bodyJsonSchema = S.object()
|
79 | .prop('residence', S.ref('https://fastify/demo#address')).required()
|
80 | .prop('office', S.ref('https://fastify/demo#/definitions/addressSchema')).required()
|
81 |
|
82 | const schema = { body: bodyJsonSchema }
|
83 |
|
84 | fastify.post('/the/url', { schema }, handler)
|
85 | ```
|
86 |
|
87 |
|
88 | **`replace-way`**: refer to a shared schema to replace before the validation process.
|
89 |
|
90 | ```js
|
91 | const sharedAddressSchema = {
|
92 | $id: 'sharedAddress',
|
93 | type: 'object',
|
94 | required: ['line1', 'country', 'city', 'zipcode'],
|
95 | properties: {
|
96 | line1: { type: 'string' },
|
97 | line2: { type: 'string' },
|
98 | country: { type: 'string' },
|
99 | city: { type: 'string' },
|
100 | zipcode: { type: 'string' }
|
101 | }
|
102 | }
|
103 | fastify.addSchema(sharedAddressSchema)
|
104 |
|
105 | const bodyJsonSchema = {
|
106 | type: 'object',
|
107 | properties: {
|
108 | vacation: 'sharedAddress#'
|
109 | }
|
110 | }
|
111 |
|
112 | const schema = { body: bodyJsonSchema }
|
113 |
|
114 | fastify.post('/the/url', { schema }, handler)
|
115 | ```
|
116 |
|
117 | NB: you can mix up the `$ref-way` and the `replace-way` when using `fastify.addSchema`.
|