|
| 1 | ++++ |
| 2 | +title = 'Components' |
| 3 | +date = 2023-12-15T09:38:53+06:00 |
| 4 | +weight = 9 |
| 5 | ++++ |
| 6 | + |
| 7 | +# Reusable Components |
| 8 | +A schema component, also known as a reusable schema fragment or sub-schema, plays a vital role in improving readability, reducing redundancy, and organizing the structure of a Schema document. In JSON validation, a schema component or fragment defines a validation rule that can be recursively composed of multiple nested validation rules, collectively specifying the expected and valid format of a JSON structure. |
| 9 | + |
| 10 | +These schema components are utilized as extensions of data type validation, as basic data types have a very limited ability to validate the internal structure of a composite JSON value or construct. Therefore, a data type is parameterized with a component to validate the internal structure of such composite JSON constructs. Moreover, schema components can be referenced from any other part of the Schema document, effectively reducing redundancy and enhancing reusability. The following example defines a simple schema component named `$component` where the validation rule describes an object structure with two key-value pairs: |
| 11 | +```js |
| 12 | +%define $component: { "key1": #integer, "key2": #string } |
| 13 | +``` |
| 14 | + |
| 15 | +A composite JSON construct is created by combining multiple values as defined by the JSON specification. These nested values can range from simple, like numbers or strings, to more complex, such as arrays or objects. While simple nested values of a composite construct can be validated using only nested data types and functions, handling hierarchical composite constructs with multiple layers of nested structures requires defining schema components. |
| 16 | + |
| 17 | +The second and third rows of the following table illustrate how the component validates the value associated with the data type for which it is used as a parameter. If the associated data type is direct, the component validates the target value itself. Conversely, if the associated data type is nested, the component validates each of the nested values comprising the composite target construct. |
| 18 | + |
| 19 | +| SN | Component Example | Valid Json | |
| 20 | +|----|----------------------------------------------------------------------------------|--------------------| |
| 21 | +| 1 | `@range*(1, 10) @length(5) #integer* #array` | `[1, 3, 5, 8, 10]` | |
| 22 | +| 2 | `%define $cmp: @range*(1, 10) #integer*` <br> `%schema: @length(5) #array($cmp)` | `[1, 3, 5, 8, 10]` | |
| 23 | +| 3 | `%define $cmp: @range(1, 10)` <br> `%schema: @length(5) #integer*($cmp) #array` | `[1, 3, 5, 8, 10]` | |
| 24 | + |
| 25 | +In the above table, all three rows have identical validation constraints for the input JSON array. This demonstrates that when dealing with simple and primitive nested values in a composite JSON construct, preferring the nested data types and functions is more convenient due to their simplicity and conciseness. However, in cases where the nested values are complex and composite, the schema component syntax becomes more suitable. The following example illustrates how the component syntax can be used to validate elements of a JSON array that are not as straightforward as the previous examples: |
| 26 | +```js |
| 27 | +%define $article: { |
| 28 | + "id": @range(1, 100) #integer, |
| 29 | + "title": @length(10, 100) #string, |
| 30 | + "preview": @length(30, 1000) #string, |
| 31 | + "tags": @length*(3, 30) @length(1, 5) #string* #array |
| 32 | +} #object |
| 33 | + |
| 34 | +%schema: @length(1, 10) #object*($article) #array |
| 35 | +``` |
| 36 | + |
| 37 | +In practical scenarios, JSON arrays often hold multiple composite JSON constructs as elements, typically sharing a recurring pattern and structure similar to the example above. To facilitate the validation of such elements, using schema components is highly effective. By defining a reusable schema component, one can improve readability, conciseness, and organization of the Schema document with such recurring structures. For instance, consider the following example of a JSON document which is valid against the Schema example above: |
| 38 | +```js |
| 39 | +[ |
| 40 | + { |
| 41 | + "id": 1, |
| 42 | + "title": "Getting Started", |
| 43 | + "preview": "This guide will show you through the essential steps to quickly...", |
| 44 | + "tags": ["JSON", "Json Schema", "Quick Start"] |
| 45 | + }, |
| 46 | + { |
| 47 | + "id": 2, |
| 48 | + "title": "Validation Syntax", |
| 49 | + "preview": "A JSON document is a structured data format used for the exchange...", |
| 50 | + "tags": ["JSON", "Json Schema", "Validation Syntax"] |
| 51 | + }, |
| 52 | + { |
| 53 | + "id": 3, |
| 54 | + "title": "Constraint Functions", |
| 55 | + "preview": "This document serves as a brief overview, providing key insights into...", |
| 56 | + "tags": ["JSON", "Json Schema", "Constraint Functions"] |
| 57 | + } |
| 58 | +] |
| 59 | +``` |
0 commit comments