[Docs] Updated 'Miscellaneous Examples' Section

pages/learn/miscellaneous-examples.md

@@ -3,6 +3,18 @@ section: docs
 title: Miscellaneous Examples
 ---
 
+In this page, you will find examples illustrating different uses cases to help you get the most out of your JSON Schemas, including:
+
+- [A typical minimum schema](#basic)
+- [Describing geographical coordinates](#describing-geographical-coordinates)
+- [Arrays of things](#arrays-of-things)
+- [Enumerated values](#enumerated-values)
+- [Regular expression pattern](#regular-expression-pattern)
+- [Complex object with nested properties](#complex-object-with-nested-properties)
+- [Conditional validation with dependentRequired](#conditional-validation-with-dependentrequired)
+- [Conditional validation with dependentSchemas](#conditional-validation-with-dependentschemas)
+- [Conditional validation with if-else](#conditional-validation-with-if-else)
+
 ## Basic
 
 This example provides a typical minimum you are likely to see in JSON Schema. It contains:
@@ -51,9 +63,12 @@ This example provides a typical minimum you are likely to see in JSON Schema. It
 }
 ```
 
-## Describing geographical coordinates.
+In the data example, we provide values for the `firstName`, `lastName`, and `age` properties. The values match the defined schema, where `firstName` is a string, `lastName` is a string, and `age` is an integer greater than or equal to zero.
+
+
+## Describing geographical coordinates
 
-This example introduces:
+In this schema, we define an object representing geographical coordinates. This example also introduces the following keywords:
 
 * [`required`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.5.3) validation keyword
 * [`minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.4) validation keyword
@@ -91,6 +106,9 @@ This example introduces:
 }
 ```
 
+The provided data contains the latitude and longitude values, both falling within the specified minimum and maximum ranges.
+
+
 ## Arrays of things
 
 Arrays are fundamental structures in JSON -- here we demonstrate a couple of ways they can be described:
@@ -103,6 +121,16 @@ We also introduce the following with this example:
 * [`$defs`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.4) keyword
 * [`$ref`](https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.3.1) keyword
 
+For the `fruits` property:
+
+* `type` is set to "array" to indicate it's an array.
+* `items` describes the items within the array. In this case, they should be of type "string".
+
+For the `vegetables` property:
+
+* `type` is also set to "array" to indicate it's an array.
+* `items` references the `$defs/veggie` definition, indicating that the items in the array should conform to the "veggie" schema defined in the `$defs` section.
+
 ```json
 {
   "$id": "https://example.com/arrays.schema.json",
@@ -157,3 +185,322 @@ We also introduce the following with this example:
   ]
 }
 ```
+
+The data example shows the usage of arrays. The `fruits` property contains an array of strings, while the `vegetables` property contains an array of objects, each adhering to the "veggie" schema definition.
+
+
+## Enumerated values
+
+This example introduces the `enum` validation keyword which is used with an array of values that includes an integer (`42`), a boolean (`true`), a string (`"hello"`), `null`, and an array (`[1, 2, 3]`). This demonstrates how `enum` can be used to specify a set of allowed values of different types.
+
+```json
+{
+  "$id": "https://example.com/enumerated-values.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Enumerated Values",
+  "type": "object",
+  "properties": {
+    "data": {
+      "enum": [42, true, "hello", null, [1, 2, 3]]
+    }
+  }
+}
+```
+
+**Data**
+
+```json
+{
+  "data": [1, 2, 3]
+}
+```
+
+The provided data adheres to the schema by using the exact values specified in the enum array: `[1, 2, 3]`.
+
+
+## Regular expression pattern
+
+This example introduces the [pattern](https://json-schema.org/draft/2020-12/json-schema-core.html#name-regular-expressions) keyword and defines an object with a property called `code` that must match a specific regular expression pattern: `^[A-Z]{3}-\d{3}$`. The pattern here requires three uppercase letters followed by a hyphen and three digits.
+
+```json
+{
+  "$id": "https://example.com/regex-pattern.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Regular Expression Pattern",
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}-\\d{3}$"
+    }
+  }
+}
+```
+
+**Data**
+
+```json
+{
+  "code": "ABC-123"
+}
+```
+
+The provided data, "ABC-123", satisfies this pattern defined in the schema.
+
+
+## Complex object with nested properties
+
+The schema below represents a complex object with various properties including `name`, `age`, `address`, and `hobbies`. The `address` property is an object with nested properties, and the `hobbies` property is an array of strings. The `name` and `age` properties are required.
+
+```json
+{
+  "$id": "https://example.com/complex-object.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Complex Object",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "age": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": {
+          "type": "string"
+        },
+        "city": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "postalCode": {
+          "type": "string",
+          "pattern": "\\d{5}"
+        }
+      },
+      "required": ["street", "city", "state", "postalCode"]
+    },
+    "hobbies": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": ["name", "age"]
+}
+```
+
+**Data**
+
+```json
+{
+  "name": "John Doe",
+  "age": 25,
+  "address": {
+    "street": "123 Main St",
+    "city": "New York",
+    "state": "NY",
+    "postalCode": "10001"
+  },
+  "hobbies": ["reading", "running"]
+}
+```
+
+The provided data conforms to the schema by including values for the required properties and ensuring the `age` is an integer greater than or equal to zero. The `address` object contains all the necessary properties, and the `hobbies` property is an array of strings.
+
+
+## Conditional validation with dependentRequired
+
+In this example, the `dependentRequired` keyword is used to specify that the property `bar` is required when the property `foo` is present. The schema enforces the condition that if `foo` exists, then `bar` must also be present.
+
+```json
+{
+  "$id": "https://example.com/conditional-validation-dependentRequired.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Conditional Validation with dependentRequired",
+  "type": "object",
+  "properties": {
+    "foo": {
+      "type": "boolean"
+    },
+    "bar": {
+      "type": "string"
+    }
+  },
+  "dependentRequired": {
+    "foo": ["bar"]
+  }
+}
+```
+
+**Data**
+
+```json
+{
+  "foo": true,
+  "bar": "Hello World"
+}
+```
+
+As per the schema, when the `foo` property is present (`true`), the `bar` property becomes required. The `bar` property is provided with the value "Hello World", satisfying the requirement of being a string and ensuring compliance with the `dependentRequired` condition.
+
+```json
+{
+}
+```
+
+Since both `foo` and `bar` are missing, the instance is still valid and in compliance with the `dependentRequired` condition as well.
+
+```json
+{
+  "foo": true
+}
+```
+
+The above schema is invalid, since the `foo` property is present, but `bar` is not, which invalidates the condition of the `dependentRequired` keyword. 
+
+
+## Conditional validation with dependentSchemas
+
+The given schema showcases the use of the `dependentSchemas` keyword. It allows defining a subschema that must be satisfied if a certain property is present. 
+
+* In this example, the schema defines an object with two properties: `foo` and `propertiesCount`. The `foo` property is of boolean type, while the `propertiesCount` property is of integer type with a minimum value of 0.
+* According to the subschema, when the `foo` property is present, the `propertiesCount` property becomes required, and must be an integer with a minimum value of 7.
+
+```json
+{
+  "$id": "https://example.com/conditional-validation-dependentSchemas.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Conditional Validation with dependentSchemas",
+  "type": "object",
+  "properties": {
+    "foo": {
+      "type": "boolean"
+    },
+    "propertiesCount": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "dependentSchemas": {
+    "foo": {
+      "required": ["propertiesCount"],
+      "properties": {
+        "propertiesCount": {
+          "minimum": 7
+        }
+      }
+    }
+  }
+}
+```
+
+**Data**
+
+```json
+{
+  "foo": true,
+  "propertiesCount": 10
+}
+```
+
+Here, the `foo` property is set to true, indicating its presence. As per the schema, when `foo` is present, the `propertiesCount` property becomes required. In this case, the `propertiesCount` property is provided with a value of 10, which satisfies the requirement of being an integer and having a minimum value of 7.
+
+```json
+{
+  "propertiesCount": 5
+}
+```
+
+In the above data, `propertiesCount` is 5 but since `foo` is missing, `propertiesCount` does not need to be 7 or more than 7, it only needs to be greater than or equal to 0. Hence, this instance is valid.
+
+```json
+{
+  "foo": true,
+  "propertiesCount": 5
+}
+```
+
+In this, we have `foo` as true, but `propertiesCount` is 5, and in the schema, `propertiesCount` is set to have minimum 7 as the input according to the `dependentSchemas`. Hence, this is an invalid instance. 
+
+
+## Conditional validation with if-else
+
+In this schema, we have two properties: `isMember` and `membershipNumber`. The conditional validation is based on the value of the `isMember` property. The validation keywords [if](https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.2.2.1), [then](https://json-schema.org/draft/2020-12/json-schema-core.html#name-then), and [else](https://json-schema.org/draft/2020-12/json-schema-core.html#name-else).
+
+Here's how the validation works in this example:
+
+If the value of `isMember` is true:
+* The `then` block is applied, which specifies that the `membershipNumber` property should be a string with a minimum length of 10 and a maximum length of 10.
+
+If the value of `isMember` is anything other than true:
+* The `else` block is applied, which specifies that the `membershipNumber` property can be any string.
+
+```json
+{
+  "$id": "https://example.com/conditional-validation-if-else.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Conditional Validation with If-Else",
+  "type": "object",
+  "properties": {
+    "isMember": {
+      "type": "boolean"
+    },
+    "membershipNumber": {
+      "type": "string"
+    }
+  },
+  "required": ["isMember"],
+  "if": {
+    "properties": {
+      "isMember": {
+        "const": true
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "membershipNumber": {
+        "type": "string",
+        "minLength": 10,
+        "maxLength": 10
+      }
+    }
+  },
+  "else": {
+    "properties": {
+      "membershipNumber": {
+        "type": "string",
+        "minLength": 15
+      }
+    }
+  }
+}
+
+```
+
+**Data**
+
+```json
+{
+  "isMember": true,
+  "membershipNumber": "1234567890"
+}
+```
+
+In this case, the `isMember` property is set to true, so the then block is applied. The `membershipNumber` property is a string with a length of 10 characters, satisfying the validation.
+
+```json
+{
+  "isMember": false,
+  "membershipNumber": "GUEST1234567890"
+}
+```
+
+In this case, the `isMember` property is false, so the else block is applied. The `membershipNumber` property can be any string with minimum length greater than or equal to 15, so it satisfies the validation.