Merge pull request #13 from relogiclabs/develop

Update Exception Handling

Author: zhossain-info

README.md

@@ -67,6 +67,7 @@ The next example represents an expanded version of the previous one, which bring
 ```cpp
 %title: "Extended User Profile Dashboard API Response"
 %version: "2.0.0-extended"
+%import: com.relogiclabs.jschema.test.external.ExternalFunctions
 
 %pragma DateDataTypeFormat: "DD-MM-YYYY"
 %pragma TimeDataTypeFormat: "DD-MM-YYYY hh:mm:ss"
@@ -105,6 +106,7 @@ The next example represents an expanded version of the previous one, which bring
         "isActive": #boolean, //user account current status
         "registeredAt": @after("01-01-2010 00:00:00") #time,
         "dataAccess": @checkAccess(&role) #integer,
+        "ipAddress": @checkIPAddress #string,
         "profile": {
             "firstName": @regex("[A-Za-z]{3,50}") #string,
             "lastName": @regex("[A-Za-z]{3,50}") #string,
@@ -140,20 +142,21 @@ The next example represents an expanded version of the previous one, which bring
         if(role == "user" && target > 5) return fail(
             "ERRACCESS01", "Data access incompatible with 'user' role",
             expected("an access at most 5 for 'user' role"),
-            actual("found access " + target + " which is greater than 5"));
+            actual("found access " + target + " that is greater than 5"));
     }
 }
 ```
 The subsequent JSON sample is an illustrative example that successfully validates against the expanded schema mentioned earlier. Within this example, recurring JSON structures appear that can be validated by defining components or nested functions and data types. Besides, reusing simple component definitions, you can achieve a clear and concise schema when validating large JSON with repetitive structures. This improves the overall readability and maintainability of the schema.
 ```json
 {
     "user": {
-        "id": 1234,
+        "id": 1111,
         "username": "johndoe",
         "role": "admin",
         "isActive": true,
         "registeredAt": "06-09-2023 15:10:30",
         "dataAccess": 10,
+        "ipAddress": "127.0.0.1",
         "profile": {
             "firstName": "John",
             "lastName": "Doe",
@@ -183,7 +186,7 @@ The subsequent JSON sample is an illustrative example that successfully validate
                 "title": "Working with JSON in Java",
                 "content": "Java provides great support for working with JSON...",
                 "tags": [
-                    "CSharp",
+                    "Java",
                     "JSON",
                     "tutorial"
                 ]

doc/content/articles/components.md

@@ -7,24 +7,25 @@ weight = 10
 # Schema Components
 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 construct.
 
-These schema components are used as an extension of data type validation, as core data types have limited features to validate the internal structure of a composite JSON value or construct. Therefore, a data type is parameterized with a schema component to validate the internal structure of such composite JSON constructs. 
+These schema components are used as an extension of data type validation, as core data types have limited features to validate the internal structure of a composite JSON value or construct. Therefore, a data type is parameterized with a schema component to validate the internal structure of such composite JSON constructs.
 
-The name or alias of a schema component always starts with `$` which also refers to the fact that they are named schema components or fragments defined elsewhere in the schema. Schema components can be referenced from any other part of the schema document, effectively reducing redundancy and enhancing reusability and readability. The following example defines a simple schema component named `$component` where the validation rule describes an object structure with two key-value pairs:
+The name or alias of a schema component always starts with `$` which unambiguously indicates that they are named schema components or fragments defined elsewhere in the schema. Schema components can be referenced from any parts of the schema document, effectively reducing redundancy and enhancing reusability and readability. The following example defines a simple schema component named `$component` where the validation rule describes an object structure with two key-value pairs:
 ```js
 %define $component: { "key1": #integer, "key2": #string }
 ```
 
 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.
 
-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.
+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.
 
 | SN | Component Example                                                                | Valid Json         |
 |----|----------------------------------------------------------------------------------|--------------------|
-| 1  | `@range*(1, 10) @length(5) #integer* #array`                                     | `[1, 3, 5, 8, 10]` |
-| 2  | `%define $cmp: @range*(1, 10) #integer*` <br> `%schema: @length(5) #array($cmp)` | `[1, 3, 5, 8, 10]` |
-| 3  | `%define $cmp: @range(1, 10)` <br> `%schema: @length(5) #integer*($cmp) #array`  | `[1, 3, 5, 8, 10]` |
+| 1  | `%schema: @range*(1, 10) @length(5) #integer* #array`                            | `[1, 3, 5, 8, 10]` |
+| 2  | `%define $cmp: @range(1, 10)` <br> `%schema: @length(5) #integer*($cmp) #array`  | `[1, 3, 5, 8, 10]` |
+| 3  | `%define $cmp: @range*(1, 10) #integer*` <br> `%schema: @length(5) #array($cmp)` | `[1, 3, 5, 8, 10]` |
+| 4  | `%define $cmp: @range*(1, 10) @length(5) #integer* #array` <br> `%schema: $cmp`  | `[1, 3, 5, 8, 10]` |
 
-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:
+In the above table, all four 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:
 ```js
 %define $article: {
     "id": @range(1, 100) #integer,
@@ -36,7 +37,7 @@ In the above table, all three rows have identical validation constraints for the
 %schema: @length(1, 10) #object*($article) #array
 ```
 
-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. 
+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 with a clear and descriptive name, one can improve the overall clarity and readability of the Schema document with recurring structures. This clarity not only makes it easier to understand the structure and intent of the schema but also contributes to keeping your complex schema well-organized, concise, and more manageable. For instance, consider the following example of a JSON document which is valid against the schema example provided above, demonstrating the usage of a schema component:
 ```js