Skip to content

Commit

Permalink
Merge pull request #48 from aku1310/examples-section
Browse files Browse the repository at this point in the history 
[Docs] Updated 'Miscellaneous Examples' Section
  • Loading branch information
@gregsdennis
gregsdennis authored Jul 19, 2023
2 parents d870f02 + 7e6cd2e commit 560b6c3
Showing 1 changed file with 349 additions and 2 deletions.
351 changes: 349 additions & 2 deletions pages/learn/miscellaneous-examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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",
Expand Down Expand Up @@ -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.

0 comments on commit 560b6c3

Please sign in to comment.