From 9b38ecde72bbadb680bd986309d292a81368932b Mon Sep 17 00:00:00 2001
From: Zahid Hossain <60911932+zhossain-info@users.noreply.github.com>
Date: Tue, 23 Jan 2024 12:57:02 +0600
Subject: [PATCH] Update project documentations
---
README.md | 8 +++---
doc/content/_index.md | 24 +++++++++++++-----
doc/content/articles/components.md | 12 ++++++---
doc/content/articles/directives.md | 6 +----
.../articles/{intro.md => introduction.md} | 10 +++++---
doc/content/articles/sourcebuild.md | 2 +-
doc/content/articles/validation.md | 22 ++++++++--------
doc/public/articles/components/index.html | 12 +++++----
doc/public/articles/datatypes/index.html | 2 +-
doc/public/articles/datetime/index.html | 2 +-
doc/public/articles/directives/index.html | 6 ++---
doc/public/articles/functions/index.html | 2 +-
doc/public/articles/index.html | 4 +--
doc/public/articles/index.xml | 13 +++++-----
.../{intro => introduction}/index.html | 11 +++++---
doc/public/articles/quickstart/index.html | 2 +-
doc/public/articles/sourcebuild/index.html | 4 +--
doc/public/articles/specification/index.html | 2 +-
doc/public/articles/validation/index.html | 23 +++++++++--------
doc/public/categories/index.html | 2 +-
doc/public/index.html | 25 ++++++++++++++-----
doc/public/index.xml | 17 +++++++------
doc/public/sitemap.xml | 2 +-
doc/public/tags/index.html | 2 +-
pom.xml | 2 +-
.../schema/external/ExternalFunctions.java | 18 +++++++------
26 files changed, 137 insertions(+), 98 deletions(-)
rename doc/content/articles/{intro.md => introduction.md} (58%)
rename doc/public/articles/{intro => introduction}/index.html (82%)
diff --git a/README.md b/README.md
index 249fac5..f29c590 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
# A New JSON Schema
-A JSON Schema is crucial for making communication, interoperability, validation, testing, documentation, and specification seamless. All of this combined contributes to better maintenance and evolution of data-driven applications and systems. For a comprehensive overview of the roles and uses of JSON Schema in modern web applications, we invite you to explore our dedicated post available [here](https://www.relogiclabs.com/2023/01/the-roles-of-json-schema.html).
+A JSON Schema is crucial for making communication, interoperability, validation, testing, documentation, and specification seamless. All of this combined contributes to better maintenance and evolution of data-driven applications and systems. If you are interested in an overview of the roles and usage of JSON Schema in modern web applications, check out our in-depth post [here](https://www.relogiclabs.com/2023/01/the-roles-of-json-schema.html).
## Design Goals
The traditional standard JSON Schema rigorously follows the conventional JSON structure, which unfortunately comes at the expense of simplicity, conciseness, and readability. Our goal is to develop a new JSON Schema that promotes these essential aspects that were previously missing.
@@ -37,7 +37,7 @@ Let's explore an example of our schema for a typical JSON API response containin
}
}
```
-In the above example, two types of constraints are used: constraint functions (also referred to as validation functions, such as `@range(1, 10000)`) and constraint data types (also referred to as validation data types, such as `#integer`). All constraint functions begin with the `@` symbol, while all constraint data types start with `#`. C-style comments are also supported within the schema. In this example, `address` can be `null` (like an optional input for users) and if it is `null` then no constraints of `address` are applicable. The following JSON is one of the examples that will be successfully validated against the above schema. To start your journey with the JSON validation library, please consult the documentation available [here](https://relogiclabs.github.io/JSchema-Java/articles/intro).
+In the above example, two types of constraints are used: constraint functions (also referred to as validation functions, such as `@range(1, 10000)`) and constraint data types (also referred to as validation data types, such as `#integer`). All constraint functions begin with the `@` symbol, while all constraint data types start with `#`. C-style comments are also supported within the schema. In this example, `address` can be `null` (like an optional input for users) and if it is `null` then no constraints of `address` are applicable. The following JSON is one of the examples that will be successfully validated against the above schema. To start your journey with the JSON validation library, please consult the documentation available [here](https://relogiclabs.github.io/JSchema-Java/articles/introduction).
```json
{
"user": {
@@ -63,7 +63,7 @@ In the above example, two types of constraints are used: constraint functions (a
}
```
## Extended Example
-The next example represents an expanded version of the previous one, which brings more complexity. To effectively construct such schemas with multiple layers of nested structures, it's beneficial to have a fundamental understanding of this schema format. While the syntax may seem difficult at first, it becomes straightforward once you have a basic understanding of it. For more detailed information, reference documentation is available [here](https://relogiclabs.github.io/JSchema-Java/articles/intro).
+The next example represents an expanded version of the previous one, which brings more complexity. To effectively construct such schemas with multiple layers of nested structures, it's beneficial to have a fundamental understanding of this schema format. While the syntax may seem difficult at first, it becomes straightforward once you have a basic understanding of it. For more detailed information, reference documentation is available [here](https://relogiclabs.github.io/JSchema-Java/articles/introduction).
```cpp
%title: "Extended User Profile Dashboard API Response"
%version: 2.0.0
@@ -171,7 +171,7 @@ The subsequent JSON sample is an illustrative example that successfully validate
{
"id": 2,
"title": "Working with JSON in Java",
- "content": "Java provides built-in support for working with JSON...",
+ "content": "Java provides great support for working with JSON...",
"tags": [
"CSharp",
"JSON",
diff --git a/doc/content/_index.md b/doc/content/_index.md
index 1dd48c8..12b3228 100644
--- a/doc/content/_index.md
+++ b/doc/content/_index.md
@@ -1,11 +1,23 @@
+++
-title = 'New Json Schema'
+title = 'Introduction'
date = 2023-10-08T09:38:53+06:00
+++
-# New Json Schema
-The New JSON Schema prioritizes simplicity, conciseness, and readability, making it user-friendly and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements. For a comprehensive overview of this JSON Schema, we invite you to explore our dedicated post available [here](https://www.relogiclabs.com/p/json-schema.html).
+# Introduction
+The New JSON Schema prioritizes simplicity, conciseness, and readability, making it intuitive and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements.
-
-
-
+JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
+
+
+ * [Getting Started & Installation](/JSchema-Java/articles/quickstart)
+ * [Validation Syntax & Format](/JSchema-Java/articles/validation)
+ * [Validation Directives & Pragmas](/JSchema-Java/articles/directives)
+ * [Schema Specification & Grammar](/JSchema-Java/articles/specification)
+ * [Data Types & Validation](/JSchema-Java/articles/datatypes)
+ * [Functions & Validation](/JSchema-Java/articles/functions)
+ * [Date & Time Patterns](/JSchema-Java/articles/datetime)
+ * [Defining Schema Components](/JSchema-Java/articles/components)
+ * [Build from Source Code](/JSchema-Java/articles/sourcebuild)
+ * [API Reference Documentation](/JSchema-Java/api/index.html)
+ * [GitHub Source Code Repository](https://github.com/relogiclabs/JSchema-Java)
+
diff --git a/doc/content/articles/components.md b/doc/content/articles/components.md
index 829b513..b13b072 100644
--- a/doc/content/articles/components.md
+++ b/doc/content/articles/components.md
@@ -4,10 +4,12 @@ date = 2023-12-15T09:38:53+06:00
weight = 9
+++
-# Reusable 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 structure.
+# 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 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:
+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:
```js
%define $component: { "key1": #integer, "key2": #string }
```
@@ -34,7 +36,9 @@ 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. 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:
+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
[
{
diff --git a/doc/content/articles/directives.md b/doc/content/articles/directives.md
index 38ab0c3..8e9253f 100644
--- a/doc/content/articles/directives.md
+++ b/doc/content/articles/directives.md
@@ -67,11 +67,7 @@ The `IgnoreObjectPropertyOrder` pragma directive provides a means to enforce a s
```
## Definition / Define Directive
-This feature in JSON schemas allows you to define a name for a component or fragment of schema or validation rules, which can be referenced from various parts of your schema. This means that if you encounter similar validation requirements in different sections of your schema, you can conveniently refer to the named component instead of duplicating the same validation rules.
-
-By providing clear and descriptive names for these validation rules or sub-schemas, you can enhance the overall clarity and context of your schema. 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 more information about the schema component syntax and format, please refer to the documentation [here](/JSchema-Java/articles/components).
-
-The name or alias of the directive is always start with `$` which also refers to that they are named fragment defined elsewhere in the schema. Here is a simple example of how to use this directive:
+This feature in JSON schemas allows you to define a name for a schema component or fragment, which can be referenced from various parts of your schema. This means that if you encounter similar validation requirements in different sections of your schema, you can conveniently refer to the named schema component instead of duplicating the same validation rules. For more information about the schema component syntax and format, please refer to the documentation [here](/JSchema-Java/articles/components). Here is a simple example of how to use this directive:
```js
%define $product: {
"id": @length(2, 10) @regex("[a-z][a-z0-9]+") #string,
diff --git a/doc/content/articles/intro.md b/doc/content/articles/introduction.md
similarity index 58%
rename from doc/content/articles/intro.md
rename to doc/content/articles/introduction.md
index a8cbea7..fa0f415 100644
--- a/doc/content/articles/intro.md
+++ b/doc/content/articles/introduction.md
@@ -5,7 +5,9 @@ weight = 1
+++
# Introduction
-JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. It allows you to specify the expected format, data types, and constraints of JSON data. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
+The New JSON Schema prioritizes simplicity, conciseness, and readability, making it intuitive and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements.
+
+JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
* [Getting Started & Installation](/JSchema-Java/articles/quickstart)
@@ -15,8 +17,8 @@ JSON, short for JavaScript Object Notation, is one of the most widely used data
* [Data Types & Validation](/JSchema-Java/articles/datatypes)
* [Functions & Validation](/JSchema-Java/articles/functions)
* [Date & Time Patterns](/JSchema-Java/articles/datetime)
- * [Reusable Components of Validation](/JSchema-Java/articles/components)
+ * [Defining Schema Components](/JSchema-Java/articles/components)
* [Build from Source Code](/JSchema-Java/articles/sourcebuild)
* [API Reference Documentation](/JSchema-Java/api/index.html)
-
-
\ No newline at end of file
+ * [GitHub Source Code Repository](https://github.com/relogiclabs/JSchema-Java)
+
diff --git a/doc/content/articles/sourcebuild.md b/doc/content/articles/sourcebuild.md
index 9ac3472..b90d62a 100644
--- a/doc/content/articles/sourcebuild.md
+++ b/doc/content/articles/sourcebuild.md
@@ -5,7 +5,7 @@ weight = 10
+++
# Build from Source Code
-This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is important to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. You also need a basic knowledge of how to work with Maven packages.
+This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is essential to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. Some basic knowledge of how to work with Maven packages would be helpful.
## Build the Library
To get started, clone the project from the following URL using your preferred Git client (command line or GUI). You can open a terminal and enter the following Git clone command as shown below:
diff --git a/doc/content/articles/validation.md b/doc/content/articles/validation.md
index 3462bc2..78d0f96 100644
--- a/doc/content/articles/validation.md
+++ b/doc/content/articles/validation.md
@@ -37,16 +37,18 @@ A JSON Schema ensures the correctness and consistency of JSON documents, and it
| 11 | `Undefined` | `!` |
| 12 | `Undefined Optional` | `! ?` |
-The syntax used in the 10th row of the table is valid, but not common in real-world scenarios. The constraint function and data type provide redundant validations, considering the validation for value is succeeded. It is generally recommended to specify the data type in all cases except in the previous scenario. Even though the functions may perform precise validations, they are typically designed to accept a broader range of data types. Therefore, specifying the data type not only makes the schema more unambiguous for readers, but also generates clear validation errors if the expected type of value is not received from the input document. For instance, the `@range` function is defined for all types of numeric input as well as dates and times. If you only accept integers for a particular field, the `@range` function without `#integer` data type cannot ensure this requirement.
+The syntax used in the 10th row of the table is valid, but not common in real-world scenarios. The constraint function and data type provide redundant validations, considering the validation for value is succeeded. It is generally recommended to specify the data type in all cases except in the previous scenario. Even though the functions may perform precise validations, they are typically designed to accept a broader range of data types.
-Now, let's explore the components of this notation and their functionalities. In the context of the validation rule, `Value` refers to a specific input JSON value of the document. This value can be either a composite value (e.g., an object or an array) or a primitive value (e.g., a string or a number).
+Therefore, specifying the data type not only makes the schema more definitive for readers, but also generates clear validation errors if the input document does not contain the expected value type. For instance, the `@range` function is defined for all types of numeric values as well as dates and times. If you only accept integers for a particular field, the `@range` function without `#integer` data type cannot ensure this requirement.
-The inclusion of `Value` in the validation rule is optional, meaning that you can choose whether or not to specify a particular JSON value for validation. However, when `Value` is present in the rule, it serves as a requirement, implying that the specified JSON value must match with the input JSON value of the document for the validation to succeed. If it does not match with the input value, the validation will fail.
+Now, let's explore the composition of this notation and its functionalities. In the context of the validation rule, `Value` refers to a specific input JSON value of the document. This value can be either a composite value (e.g., an object or an array) or a primitive value (e.g., a string or a number).
+
+The inclusion of `Value` in the validation rule is optional, meaning that you can choose whether or not to specify a particular JSON value for validation. However, when `Value` is present in the rule, it serves as a requirement, implying that the specified JSON value must match with the input JSON value of the document for the validation to succeed.
The `Function-Set` is an optional part of the validation rule that can contain one or more function constraints. Function constraints are restrictions or conditions that validate the input JSON value. These functions can be of two types based on their application:
1. Direct functions are applied directly to the target value itself for which the validation rule is defined.
- 2. Nested functions are applied to the nested values or items within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk `*` is used after the function name to indicate that the constraint function is applied to the nested values.
+ 2. Nested functions are applied to the nested values or nested components within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk `*` is used after the function name to indicate that the constraint function is applied only to the nested values.
The validation of the `Function-Set` as a whole is considered successful only if each function constraint within it succeeds, regardless of its type and application mode.
@@ -57,10 +59,10 @@ The validation of the `Function-Set` as a whole is considered successful only if
| 3 | `@length(1, 15)` | `"lorem"`; `"lorem ipsum"` | `""`; `"lorem ipsum dolor"` |
| 4 | `@length*(1, 15)` | `["lorem", "lorem ipsum"]` | `["lorem", "lorem ipsum dolor"]` |
-Similar to the `Function-Set`, the `Datatype-Set` is also an optional part of the validation rule and can contain one or more data type constraints. Data type constraints specify the expected data types that validate the input JSON value itself or its nested components, depending on whether the value is composite or primitive and whether its application mode is direct or nested. As like function constraints data types can be of two types based on their application:
+Similar to the `Function-Set`, the `Datatype-Set` is also an optional part of the validation rule and can contain one or more data type constraints. Data type constraints specify the expected data types that validate the input JSON value itself or its nested values, depending on whether the value is composite or primitive and whether its application mode is direct or nested. As like function constraints data types can be of two types based on their application:
1. Direct data types are applied directly to the target value itself for which the validation rule is defined.
- 2. Nested data type applied to the nested values or items within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk `*` is used after the data type name to indicate that the data type is applied to the nested values.
+ 2. Nested data type applied to the nested values or nested components within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk `*` is used after the data type name to indicate that the data type is applied only to the nested values.
Validation of the `Datatype-Set` is deemed successful if validation is successful for one of the direct (type 1) data types and one of the nested (type 2) data types. This becomes particularly relevant in several real-world scenarios including those where a composite target value, such as an array or object, is also allowed to be null.
@@ -74,14 +76,14 @@ Validation of the `Datatype-Set` is deemed successful if validation is successfu
| 6 | `#array #null` | `[10, 20, 30]`; `null` | `10`; `100.5`; `"lorem"` |
| 7 | `#integer* #float* #array` | `[10, 10.5, 100]` | `[10, "lorem", false, null]` |
-When defining nested types for values or elements for a composite type, it is good practice to also define the direct type (eg. `#array` and `#object`) that not only makes the schema more convenient for readers but also generates more straightforward validation errors if they occur, but it is optional. Moreover, each nested value must belong to one of the nested types specified in a validation rule.
+When defining nested types for values or elements of a composite type, it is recommended to also define the direct type (eg. `#array` and `#object`) that not only makes the schema more convenient for readers but also generates more straightforward validation errors if they occur, but it is optional. Moreover, each nested value must belong to one of the nested types specified in the validation rule for the validation to succeed.
The `Receiver-Set` is also an optional part of the validation rule, and it can consist of one or more receivers. A receiver is identified by its name always prefixed by `&` and can receive or store the input JSON values of that position. A validation function can accept receivers and validate input based on the received values of the receivers.
Moreover, one receiver can be used in multiple validation rules and one validation rule can contain multiple receivers. This flexibility facilitates the organization and utilization of receivers in a more coherent and readable manner in a schema. Depending on its position a receiver can receive zero or more JSON input values. For instance, if a receiver is placed inside a common element section of an array, it will receive zero value if the array is empty and many values if it contains many elements.
-The `Optional` marker, denoted as `?`, specifies that the presence of the target value is optional within the input JSON document. When `Optional` is specified, it indicates that the target value may or may not be present. If it is absent, no validation is performed for that specific target value, and the JSON document is considered valid.
+The `Optional` marker, denoted as `?`, specifies that the presence of the target value is optional within the input JSON document. If the target value is absent, no validation is performed, and the JSON document is considered valid.
-However, if the target value is present, the validation rule must succeed for the document to be considered valid and conform to the Schema. Failure to meet the validation rule renders the JSON document invalid. The absence of the `Optional` specifier requires the target JSON value to be present in the input JSON document for validation to succeed.
+However, if the target value is present, the validation rule must succeed for the document to be considered valid and conform to the Schema. The absence of the `Optional` specifier requires the target JSON value to be present in the input JSON document for validation to succeed.
-In instances where no validation rule (or no segments of the validation rule) is explicitly defined for a target input JSON value, the use of the undefined marker `!` signifies that any valid JSON value is acceptable for the target. This allows more flexibility in JSON data validation for specific cases.
\ No newline at end of file
+In instances where no validation rule (or no parts of the validation rule) is explicitly defined for a target input JSON value, the use of the undefined marker `!` signifies that any valid JSON value is acceptable for the target. This allows more flexibility in JSON data validation for specific cases.
diff --git a/doc/public/articles/components/index.html b/doc/public/articles/components/index.html
index 28cec96..9c929e6 100644
--- a/doc/public/articles/components/index.html
+++ b/doc/public/articles/components/index.html
@@ -32,7 +32,7 @@
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.
-
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:
+
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.
+
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:
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.
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:
+
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:
The IgnoreObjectPropertyOrder pragma directive provides a means to enforce a specific order or sequence of JSON object properties, following the schema definition. This requirement for strict ordering is only needed in certain special cases. By default, this directive is set to true, meaning that the object property order outlined in the schema document is not mandatory. However, you can override this default by setting it to false, as shown in the following example below:
%pragmaIgnoreObjectPropertyOrder:false
Definition / Define Directive
-
This feature in JSON schemas allows you to define a name for a component or fragment of schema or validation rules, which can be referenced from various parts of your schema. This means that if you encounter similar validation requirements in different sections of your schema, you can conveniently refer to the named component instead of duplicating the same validation rules.
-
By providing clear and descriptive names for these validation rules or sub-schemas, you can enhance the overall clarity and context of your schema. 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 more information about the schema component syntax and format, please refer to the documentation here.
-
The name or alias of the directive is always start with $ which also refers to that they are named fragment defined elsewhere in the schema. Here is a simple example of how to use this directive:
+
This feature in JSON schemas allows you to define a name for a schema component or fragment, which can be referenced from various parts of your schema. This means that if you encounter similar validation requirements in different sections of your schema, you can conveniently refer to the named schema component instead of duplicating the same validation rules. For more information about the schema component syntax and format, please refer to the documentation here. Here is a simple example of how to use this directive:
diff --git a/doc/public/articles/index.xml b/doc/public/articles/index.xml
index e7a945b..7ee7905 100644
--- a/doc/public/articles/index.xml
+++ b/doc/public/articles/index.xml
@@ -9,11 +9,12 @@
Sun, 08 Oct 2023 09:38:53 +0600Introduction
- https://relogiclabs.github.io/JSchema-Java/articles/intro/
+ https://relogiclabs.github.io/JSchema-Java/articles/introduction/
Sun, 08 Oct 2023 09:38:53 +0600
- https://relogiclabs.github.io/JSchema-Java/articles/intro/
- Introduction JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. It allows you to specify the expected format, data types, and constraints of JSON data. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
+ https://relogiclabs.github.io/JSchema-Java/articles/introduction/
+ Introduction The New JSON Schema prioritizes simplicity, conciseness, and readability, making it intuitive and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements.
+JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents.
@@ -91,8 +92,8 @@ Date and time formats are defined using date and time pattern strings. Within th
Fri, 15 Dec 2023 09:38:53 +0600https://relogiclabs.github.io/JSchema-Java/articles/components/
- Reusable 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 structure.
-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.
+ 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.
@@ -101,7 +102,7 @@ These schema components are utilized as extensions of data type validation, as b
Mon, 04 Dec 2023 09:38:53 +0600https://relogiclabs.github.io/JSchema-Java/articles/sourcebuild/
- Build from Source Code This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is important to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. You also need a basic knowledge of how to work with Maven packages.
+ Build from Source Code This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is essential to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. Some basic knowledge of how to work with Maven packages would be helpful.
diff --git a/doc/public/articles/intro/index.html b/doc/public/articles/introduction/index.html
similarity index 82%
rename from doc/public/articles/intro/index.html
rename to doc/public/articles/introduction/index.html
index 92b8e93..6be00f4 100644
--- a/doc/public/articles/intro/index.html
+++ b/doc/public/articles/introduction/index.html
@@ -32,7 +32,7 @@
JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. It allows you to specify the expected format, data types, and constraints of JSON data. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
+
The New JSON Schema prioritizes simplicity, conciseness, and readability, making it intuitive and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements.
+
JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is important to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. You also need a basic knowledge of how to work with Maven packages.
+
This comprehensive guide illustrates the procedures for retrieving source code from a GitHub repository, compiling the project source code into a library, and seamlessly integrating the compiled library into your project. It is essential to have a foundational understanding of the Java language, as well as a modest level of familiarity with the Java SDK and command-line interface. Some basic knowledge of how to work with Maven packages would be helpful.
Build the Library
To get started, clone the project from the following URL using your preferred Git client (command line or GUI). You can open a terminal and enter the following Git clone command as shown below:
The syntax used in the 10th row of the table is valid, but not common in real-world scenarios. The constraint function and data type provide redundant validations, considering the validation for value is succeeded. It is generally recommended to specify the data type in all cases except in the previous scenario. Even though the functions may perform precise validations, they are typically designed to accept a broader range of data types. Therefore, specifying the data type not only makes the schema more unambiguous for readers, but also generates clear validation errors if the expected type of value is not received from the input document. For instance, the @range function is defined for all types of numeric input as well as dates and times. If you only accept integers for a particular field, the @range function without #integer data type cannot ensure this requirement.
-
Now, let’s explore the components of this notation and their functionalities. In the context of the validation rule, Value refers to a specific input JSON value of the document. This value can be either a composite value (e.g., an object or an array) or a primitive value (e.g., a string or a number).
-
The inclusion of Value in the validation rule is optional, meaning that you can choose whether or not to specify a particular JSON value for validation. However, when Value is present in the rule, it serves as a requirement, implying that the specified JSON value must match with the input JSON value of the document for the validation to succeed. If it does not match with the input value, the validation will fail.
+
The syntax used in the 10th row of the table is valid, but not common in real-world scenarios. The constraint function and data type provide redundant validations, considering the validation for value is succeeded. It is generally recommended to specify the data type in all cases except in the previous scenario. Even though the functions may perform precise validations, they are typically designed to accept a broader range of data types.
+
Therefore, specifying the data type not only makes the schema more definitive for readers, but also generates clear validation errors if the input document does not contain the expected value type. For instance, the @range function is defined for all types of numeric values as well as dates and times. If you only accept integers for a particular field, the @range function without #integer data type cannot ensure this requirement.
+
Now, let’s explore the composition of this notation and its functionalities. In the context of the validation rule, Value refers to a specific input JSON value of the document. This value can be either a composite value (e.g., an object or an array) or a primitive value (e.g., a string or a number).
+
The inclusion of Value in the validation rule is optional, meaning that you can choose whether or not to specify a particular JSON value for validation. However, when Value is present in the rule, it serves as a requirement, implying that the specified JSON value must match with the input JSON value of the document for the validation to succeed.
The Function-Set is an optional part of the validation rule that can contain one or more function constraints. Function constraints are restrictions or conditions that validate the input JSON value. These functions can be of two types based on their application:
Direct functions are applied directly to the target value itself for which the validation rule is defined.
-
Nested functions are applied to the nested values or items within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk * is used after the function name to indicate that the constraint function is applied to the nested values.
+
Nested functions are applied to the nested values or nested components within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk * is used after the function name to indicate that the constraint function is applied only to the nested values.
The validation of the Function-Set as a whole is considered successful only if each function constraint within it succeeds, regardless of its type and application mode.
@@ -202,10 +203,10 @@
Validation Format
-
Similar to the Function-Set, the Datatype-Set is also an optional part of the validation rule and can contain one or more data type constraints. Data type constraints specify the expected data types that validate the input JSON value itself or its nested components, depending on whether the value is composite or primitive and whether its application mode is direct or nested. As like function constraints data types can be of two types based on their application:
+
Similar to the Function-Set, the Datatype-Set is also an optional part of the validation rule and can contain one or more data type constraints. Data type constraints specify the expected data types that validate the input JSON value itself or its nested values, depending on whether the value is composite or primitive and whether its application mode is direct or nested. As like function constraints data types can be of two types based on their application:
Direct data types are applied directly to the target value itself for which the validation rule is defined.
-
Nested data type applied to the nested values or items within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk * is used after the data type name to indicate that the data type is applied to the nested values.
+
Nested data type applied to the nested values or nested components within the target value. They are applicable and valid only if the target value is a composite JSON value. An asterisk * is used after the data type name to indicate that the data type is applied only to the nested values.
Validation of the Datatype-Set is deemed successful if validation is successful for one of the direct (type 1) data types and one of the nested (type 2) data types. This becomes particularly relevant in several real-world scenarios including those where a composite target value, such as an array or object, is also allowed to be null.
@@ -262,12 +263,12 @@
Validation Format
-
When defining nested types for values or elements for a composite type, it is good practice to also define the direct type (eg. #array and #object) that not only makes the schema more convenient for readers but also generates more straightforward validation errors if they occur, but it is optional. Moreover, each nested value must belong to one of the nested types specified in a validation rule.
+
When defining nested types for values or elements of a composite type, it is recommended to also define the direct type (eg. #array and #object) that not only makes the schema more convenient for readers but also generates more straightforward validation errors if they occur, but it is optional. Moreover, each nested value must belong to one of the nested types specified in the validation rule for the validation to succeed.
The Receiver-Set is also an optional part of the validation rule, and it can consist of one or more receivers. A receiver is identified by its name always prefixed by & and can receive or store the input JSON values of that position. A validation function can accept receivers and validate input based on the received values of the receivers.
Moreover, one receiver can be used in multiple validation rules and one validation rule can contain multiple receivers. This flexibility facilitates the organization and utilization of receivers in a more coherent and readable manner in a schema. Depending on its position a receiver can receive zero or more JSON input values. For instance, if a receiver is placed inside a common element section of an array, it will receive zero value if the array is empty and many values if it contains many elements.
-
The Optional marker, denoted as ?, specifies that the presence of the target value is optional within the input JSON document. When Optional is specified, it indicates that the target value may or may not be present. If it is absent, no validation is performed for that specific target value, and the JSON document is considered valid.
-
However, if the target value is present, the validation rule must succeed for the document to be considered valid and conform to the Schema. Failure to meet the validation rule renders the JSON document invalid. The absence of the Optional specifier requires the target JSON value to be present in the input JSON document for validation to succeed.
-
In instances where no validation rule (or no segments of the validation rule) is explicitly defined for a target input JSON value, the use of the undefined marker ! signifies that any valid JSON value is acceptable for the target. This allows more flexibility in JSON data validation for specific cases.
+
The Optional marker, denoted as ?, specifies that the presence of the target value is optional within the input JSON document. If the target value is absent, no validation is performed, and the JSON document is considered valid.
+
However, if the target value is present, the validation rule must succeed for the document to be considered valid and conform to the Schema. The absence of the Optional specifier requires the target JSON value to be present in the input JSON document for validation to succeed.
+
In instances where no validation rule (or no parts of the validation rule) is explicitly defined for a target input JSON value, the use of the undefined marker ! signifies that any valid JSON value is acceptable for the target. This allows more flexibility in JSON data validation for specific cases.
The New JSON Schema prioritizes simplicity, conciseness, and readability, making it user-friendly and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements. For a comprehensive overview of this JSON Schema, we invite you to explore our dedicated post available here.
-
-
-
+
Introduction
+
The New JSON Schema prioritizes simplicity, conciseness, and readability, making it intuitive and accessible without the need for extensive prior knowledge. It offers efficient read-write facilities, precise JSON document definition through various data types and functions, and extensibility to meet modern web service diverse requirements.
+
JSON, short for JavaScript Object Notation, is one of the most widely used data exchange formats that are both user-friendly and machine-readable. New JSON Schema is a practical tool for defining and validating the structure of JSON documents. The following guides offer comprehensive details about the New JSON Schema. This document provides a list of links, each corresponding to a specific detail document available in this project.
+
-