Merge pull request #5 from relogiclabs/develop

Add Deferred Validation and Receiver Features

Author: zhossain-info

README.md

@@ -68,6 +68,9 @@ The next example represents an expanded version of the previous one, which bring
 %title: "Extended User Profile Dashboard API Response"
 %version: 2.0.0
 %include: com.relogiclabs.json.schema.positive.ExternalFunctions
+
+%pragma DateDataTypeFormat: "DD-MM-YYYY"
+%pragma TimeDataTypeFormat: "DD-MM-YYYY hh:mm:ss"
 %pragma IgnoreUndefinedProperties: true
 
 %define $post: {
@@ -99,13 +102,14 @@ The next example represents an expanded version of the previous one, which bring
         "id": @range(1, 10000) #integer,
         /*username does not allow special characters*/
         "username": @regex("[a-z_]{3,30}") #string,
-        "role": @enum("user", "admin") #string,
+        "role": @enum("user", "admin") #string &role,
         "isActive": #boolean, //user account current status
-        "registeredAt": @time("DD-MM-YYYY hh:mm:ss") #string,
+        "registeredAt": @after("01-01-2010 00:00:00") #time,
+        "dataAccess": @checkAccess(&role) #integer,
         "profile": {
             "firstName": @regex("[A-Za-z]{3,50}") #string,
             "lastName": @regex("[A-Za-z]{3,50}") #string,
-            "dateOfBirth": @date("DD-MM-YYYY") #string,
+            "dateOfBirth": @before("01-01-2006") #date,
             "age": @range(18, 128) #integer,
             "email": @email #string,
             "pictureURL": @url #string,
@@ -125,7 +129,7 @@ The next example represents an expanded version of the previous one, which bring
     },
     "products": #object*($product) #array,
     "weather": {
-        "temperature": @range(-50.0, 60.0) #float,
+        "temperature": @range(-50, 60) #integer #float,
         "isCloudy": #boolean
     }
 }
@@ -139,6 +143,7 @@ The subsequent JSON sample is an illustrative example that successfully validate
         "role": "admin",
         "isActive": true,
         "registeredAt": "06-09-2023 15:10:30",
+        "dataAccess": 10,
         "profile": {
             "firstName": "John",
             "lastName": "Doe",
@@ -195,7 +200,7 @@ The subsequent JSON sample is an illustrative example that successfully validate
             "id": "p1",
             "name": "Smartphone",
             "brand": "TechGiant",
-            "price": 599.99,
+            "price": 1.99,
             "inStock": true,
             "specs": null
         },
@@ -219,4 +224,4 @@ The subsequent JSON sample is an illustrative example that successfully validate
     }
 }
 ```
-For more information about the schema syntax format and library functionalities, please refer to the reference documentation [here](https://relogiclabs.github.io/JsonSchema-Java/api/index.html).
+For more information about the schema syntax format and library functionalities, please refer to the reference documentation [here](https://relogiclabs.github.io/JsonSchema-Java/api/index.html).

doc/content/articles/datatypes.md

@@ -1,6 +1,6 @@
 +++
 title = 'Data Types'
-date = 2023-10-08T09:38:53+06:00
+date = 2023-12-04T09:38:53+06:00
 weight = 6
 +++
 
@@ -16,19 +16,25 @@ In the schema document, data types are denoted by the `#` prefix. Here is an out
 ```html
 #any
  ┬
- ├ #object
- ├ #array
- ├ #string
+ ├ #primitive
  │  ┬
- │  ├ #date
- │  └ #time
- ├ #number
- │  ┬
- │  ├ #integer
- │  ├ #float
- │  └ #double  
- ├ #boolean
- └ #null
+ │  ├ #string
+ │  │  ┬
+ │  │  └ #datetime
+ │  │     ┬
+ │  │     ├ #date
+ │  │     └ #time
+ │  ├ #number
+ │  │  ┬
+ │  │  ├ #integer
+ │  │  ├ #float
+ │  │  └ #double  
+ │  ├ #boolean
+ │  └ #null  
+ └ #composite
+    ┬
+    ├ #array
+    └ #object
 ```
 
 ### The Any Data Type
@@ -37,10 +43,16 @@ This data type accepts any valid JSON value that conforms to the JSON standard.
 #any
 ```
 
-### The Object Data Type
-This data type represents the JSON object type and accepts any JSON object specified by the JSON standard. The specification document for JSON provides details about the different syntax and forms of JSON objects. Following is the syntax for specifying this data type:
+### The Primitive Data Type
+This serves as the foundational data type for all non-composite or primitive JSON values. While it is not intended for direct use in a schema, it organizes common functionalities across other sub-data types. Nevertheless, it remains valid for use, as illustrated by the following syntax:
 ```html
-#object
+#primitive
+```
+
+### The Composite Data Type
+As the parent data type for two kinds of composite JSON values, namely arrays and objects, this composite type consists of zero or more JSON values. It is not designed to be used in a schema but rather the organization of shared functionalities among other sub-data types. Despite this, it is still valid for use, demonstrated by the following syntax:
+```html
+#composite
 ```
 
 ### The Array Data Type
@@ -49,20 +61,32 @@ This data type represents the JSON array type and accepts any JSON array specifi
 #array
 ```
 
+### The Object Data Type
+This data type represents the JSON object type and accepts any JSON object specified by the JSON standard. The specification document for JSON provides details about the different syntax and forms of JSON objects. Following is the syntax for specifying this data type:
+```html
+#object
+```
+
 ### The String Data Type
 This is one of the most commonly used data types in a JSON document, designed to accept any JSON string as specified by the JSON standard. The syntax for specifying this data type is as follows:
 ```html
 #string
 ```
 
+### The Date Time Data Type
+The date-time data type serves as the parent data type for both date and time types. It is a subtype of JSON string type and thus formatted as per the JSON string specification. It is not intended to be used directly in a schema, but it provides common functionality for both date and time types.
+```html
+#datetime
+```
+
 ### The Date Data Type
-The date data type accepts only a type of string which represent a date specified by ISO 8601 standard (date part only). It is a subtype of string data type and thus formatted as per the JSON string specification. Detailed explanations of the ISO 8601 standard can be found in this [document](https://www.iso.org/iso-8601-date-and-time-format.html). Furthermore, you can refer to this [document](/JsonSchema-DotNet/articles/datetime.html) for a detailed description of the date pattern associated with this data type. To define this data type in schema, use the following syntax:
+The date data type accepts a string representation of a date, conforming to the ISO 8601 standard (date part only). This is the default configuration, which can be modified using the directive described [here](/JsonSchema-Java/articles/directives). It is a subtype of date-time type and thus also formatted as per the JSON string specification. Detailed explanations of the ISO 8601 standard can be found in this [document](https://www.iso.org/iso-8601-date-and-time-format.html). Furthermore, you can refer to this [document](/JsonSchema-Java/articles/datetime) for a detailed description of the date pattern associated with this data type. To define this data type in schema, use the following syntax:
 ```html
 #date
 ```
 
 ### The Time Data Type
-The time data type only accepts strings representing date-time (including both date and time), in accordance with the ISO 8601 standard. Similar to the date data type, it is a subtype of string data type and thus formatted as per the JSON string specification. Here is the ISO 8601 standard [document](https://www.iso.org/iso-8601-date-and-time-format.html), which contains detailed explanations. Furthermore, you can refer to this [document](/JsonSchema-DotNet/articles/datetime.html) for a detailed description of the date-time pattern associated with this data type. To define this data type in schema, use the following syntax:
+The time data type accepts a string representation of a time (including both date and time parts), in accordance with the ISO 8601 standard. This default configuration can be modified using the directive described [here](/JsonSchema-Java/articles/directives). Similar to the date data type, it is a subtype of date-time data type and thus also formatted as per the JSON string specification. Here is the ISO 8601 standard [document](https://www.iso.org/iso-8601-date-and-time-format.html), which contains detailed explanations. Furthermore, you can refer to this [document](/JsonSchema-Java/articles/datetime) for a detailed description of the date-time pattern associated with this data type. To define this data type in schema, use the following syntax:
 ```html
 #time
 ```

doc/content/articles/directives.md

@@ -1,6 +1,6 @@
 +++
 title = 'Directives'
-date = 2023-10-08T09:38:53+06:00
+date = 2023-12-04T09:38:53+06:00
 weight = 4
 +++
 
@@ -42,6 +42,18 @@ The default value of this directive is `false`, which means that by default, und
 %pragma IgnoreUndefinedProperties: true
 ```
 
+### Date Data Type Format
+The `DateDataTypeFormat` pragma directive enables you to customize the default format of the `#date` data type. By default, the `#date` data type follows the ISO 8601 standard, precisely using the format `YYYY-MM-DD`. Additional details on date-time patterns and formats are available [here](/JsonSchema-Java/articles/datetime). The subsequent example illustrates the process of defining a customized date format for the `#date` data type:
+```js
+%pragma DateDataTypeFormat: "DD-MM-YYYY"
+```
+
+### Time Data Type Format
+To customize the default format of the `#time` data type, utilize the `TimeDataTypeFormat` pragma directive. By default, the `#time` data type follows the ISO 8601 standard, precisely in the format `YYYY-MM-DD'T'hh:mm:ss.FZZ`. Further information on date-time patterns and formats can be found [here](/JsonSchema-Java/articles/datetime). The following example demonstrates how to specify a customized time format for the `#time` data type:
+```js
+%pragma TimeDataTypeFormat: "DD-MM-YYYY hh:mm:ss"
+```
+
 ### Floating Point Tolerance
 The `FloatingPointTolerance` pragma directive allows you to define the tolerance level for relative errors in floating-point numbers during calculations and computations carried out by the validation process. By default, this directive is set to `1E-10`, indicating a small tolerance. However, you have the flexibility to adjust this value to any desired number. To specify a custom tolerance value of `1E-07`, you can use the following notation as an example:
 ```js

doc/content/articles/functions.md

@@ -1,6 +1,6 @@
 +++
 title = 'Functions'
-date = 2023-10-08T09:38:53+06:00
+date = 2023-12-04T09:38:53+06:00
 weight = 7
 +++
 
@@ -184,13 +184,51 @@ Validates whether the `target` string is a valid phone number. It follows the IT
 ```stylus
 #string target - @date(pattern)
 ```
-Validates that the `target` string matches the date and time pattern specified by the `pattern` parameter. It fully supports the ISO 8601 date and time format. Beyond this standard, it also allows custom date and time formats, ensuring compatibility with various systems and meeting diverse users and businesses requirements. This [document](/JsonSchema-DotNet/articles/datetime.html) provides a comprehensive overview of the date-time custom patterns.
+Validates that the `target` string matches the date and time pattern specified by the `pattern` parameter. It fully supports the ISO 8601 date and time format. Beyond this standard, it also allows custom date and time formats, ensuring compatibility with various systems and meeting diverse users and businesses requirements. This [document](/JsonSchema-Java/articles/datetime) provides a comprehensive overview of the date-time custom patterns.
 
 ```
 #string target - @time(pattern)
 ```
-Both the `@date` and `@time` functions support a complete range of date-time patterns, enabling the precise definition of any date and time scenario. Therefore, these functions can be used interchangeably. When the sole consideration is the date or day of the month in a year, employing the `@date` function is the more convenient choice. In contrast, when it becomes necessary to specify a particular time on a date, the `@time` function is the more appropriate option. To learn more about date-time patterns, please refer to [this page](/JsonSchema-DotNet/articles/datetime.html).
+Both the `@date` and `@time` functions support a complete range of date-time patterns, enabling the precise definition of any date and time scenario. Therefore, these functions can be used interchangeably. When the sole consideration is the date or day of the month in a year, employing the `@date` function is the more convenient choice. In contrast, when it becomes necessary to specify a particular time on a date, the `@time` function is the more appropriate option. To learn more about date-time patterns, please refer to [this page](/JsonSchema-Java/articles/datetime).
 
+### Date and Time Range
+```stylus
+#datetime target - @range(#string start, #string end)
+```
+Validates that the `target` date-time satisfies the range requirement specified by the parameters. It checks that the `target` date-time is from or after the `start` date-time specified and simultaneously until and before the `end` date-time specified. If not, a validation error will generate. The `start` and `end` parameters must be the string representation of the `target` data type, which can either be a `#date` or `#time` type.
+
+If either the parameter values for `start` or `end` are unspecified or undefined, the `undefined` symbol `!` can be used in place of either of these parameters. The following examples illustrate the various use cases of the `@range` function of the two variations described above, for the target type:
+
+| Ues Cases                                                        | Valid Values                                           | Invalid Values                           |
+|------------------------------------------------------------------|--------------------------------------------------------|------------------------------------------|
+| `@range("2010-01-01", "2010-12-31")`                             | `2010-01-01`; `2010-06-30`; `2010-12-31`               | `2009-12-31`; `2011-01-01`; `2030-11-05` |
+| `@range("2010-01-01T00:00:00.000Z", "2010-12-31T23:59:59.999Z")` | `2010-01-01T00:00:00.000Z`; `2010-12-31T23:59:59.999Z` | `2009-12-31T23:59:59.999Z`               |
+| `@range(!, "2010-12-31")`                                        | `1990-01-01`; `2010-12-31`                             | `2011-01-01`; `2030-11-05`               |
+| `@range("2010-01-01", !)`                                        | `2010-01-01`; `2030-11-05`                             | `1990-01-01`; `2009-12-31`               |
+
+### Date and Time Start
+```stylus
+#datetime target - @start(#string reference)
+```
+Validates that the `target` date-time starts from or finds after the specified `reference` date-time parameter. If the `target` date-time finds before the `reference` date-time, a validation error is triggered. The `reference` parameter must be the string representation of the `target` data type, which can either be a `#date` or `#time` type.
+
+### Date and Time End
+```stylus
+#datetime target - @end(#string reference)
+```
+Validates that the `target` date-time finds before or ends at the specified `reference` date-time parameter. If the `target` date-time finds after the `reference` date-time, a validation error is triggered. The `reference` parameter must be the string representation of the `target` data type, which can either be a `#date` or `#time` type.
+
+### Date and Time Before
+```stylus
+#datetime target - @before(#string reference)
+```
+Validates that the `target` date-time is exclusively before the `reference` date-time. If the `target` date-time finds on or after the `reference` date-time, a validation error is triggered. The `reference` parameter must be the string representation of the `target` data type, which can either be a `#date` or `#time` type.
+
+### Date and Time After
+```stylus
+#datetime target - @after(#string reference)
+```
+Validates that the `target` date-time is exclusively after the `reference` date-time. If the `target` date-time finds on or before the `reference` date-time, a validation error is triggered. The `reference` parameter must be the string representation of the `target` data type, which can either be a `#date` or `#time` type.
 
 ### Number Positive
 ```stylus

doc/content/articles/quickstart.md

@@ -160,4 +160,4 @@ Actual (Json Line: 3:14): found #string inferred by "not number"
 	at org.example.SampleSchema.checkIsValid(SampleSchema.java:64)
 	at org.example.Main.main(Main.java:5)
 ```
-For more information about the schema syntax format and library functionalities, please refer to the reference documentation [here](/JsonSchema-Java/api/index.html).
+For more information about the schema syntax format and library functionalities, please refer to the reference documentation [here](/JsonSchema-Java/api/index.html).

doc/content/articles/sourcebuild.md

@@ -1,6 +1,6 @@
 +++
 title = 'Source Build'
-date = 2023-11-03T09:38:53+06:00
+date = 2023-12-04T09:38:53+06:00
 weight = 9
 +++
 

doc/content/articles/specification.md

@@ -79,7 +79,7 @@ validator
     alias-name
 
 validator-main
-    value-opt functions-opt datatypes-opt this-opt
+    value-opt functions-opt datatypes-opt receivers-opt this-opt
 
 value-opt
     ''
@@ -98,20 +98,24 @@ functions
     function functions
 
 function
-    function-name function-params-opt
+    function-name function-args-opt
 
 function-name
     '@' identifier
     '@' identifier '*'
 
-function-params-opt
+function-args-opt
     ''
     '(' ')'
-    '(' function-params ')'
+    '(' function-args ')'
 
-function-params
+function-args
+    function-arg
+    function-arg ',' function-args
+
+function-arg
     value
-    value ',' function-params
+    receiver
 
 datatypes-opt
     ''
@@ -121,7 +125,7 @@ datatypes
     datatype datatypes
 
 datatype
-    datatype-name datatype-param-opt
+    datatype-name datatype-arg-opt
 
 datatype-name
     '#' alphas
@@ -130,10 +134,20 @@ datatype-name
 alphas
     alpha alphas
 
-datatype-param-opt
+datatype-arg-opt
     ''
     '(' alias-name ')'
 
+receivers-opt
+    ''
+    receivers
+
+receivers
+    receiver receivers
+
+receiver
+    '&' identifier
+
 this-opt
     ''
     '?'