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