From 4e7e1c780ffd8d762f6c339ba621f45ec948275c Mon Sep 17 00:00:00 2001 From: techmannih Date: Mon, 2 Dec 2024 22:32:43 +0530 Subject: [PATCH 1/3] add introductory guide to JSON Schema --- components/Sidebar.tsx | 6 + .../understanding-json-schema/introduction.md | 224 ++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 pages/understanding-json-schema/introduction.md diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index 6370bb406..80ff241a1 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -122,6 +122,7 @@ const getReferencePath = [ '/understanding-json-schema', '/understanding-json-schema/keywords', '/understanding-json-schema/basics', + '/understanding-json-schema/introduction', '/understanding-json-schema/conventions', '/understanding-json-schema/about', '/understanding-json-schema/credits', @@ -525,6 +526,11 @@ export const DocsNav = ({ uri='/understanding-json-schema/conventions' label='Conventions used' setOpen={setOpen} + /> + Date: Sat, 21 Dec 2024 19:21:55 +0530 Subject: [PATCH 2/3] fix lint error --- components/Sidebar.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/Sidebar.tsx b/components/Sidebar.tsx index 80ff241a1..554f4feb1 100644 --- a/components/Sidebar.tsx +++ b/components/Sidebar.tsx @@ -527,7 +527,7 @@ export const DocsNav = ({ label='Conventions used' setOpen={setOpen} /> - Date: Mon, 23 Dec 2024 23:36:14 +0530 Subject: [PATCH 3/3] fix format and sentence case --- .../understanding-json-schema/introduction.md | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/pages/understanding-json-schema/introduction.md b/pages/understanding-json-schema/introduction.md index d2a25a443..fc7fa6a02 100644 --- a/pages/understanding-json-schema/introduction.md +++ b/pages/understanding-json-schema/introduction.md @@ -6,13 +6,13 @@ section: docs ## What is JSON Schema? JSON Schema is a declarative language for defining the structure and constraints of JSON data. It serves as both a blueprint and validation tool, ensuring that JSON data adheres to expected formats and structures. -### Why Use JSON Schema? +### Why use JSON Schema? - **Validation**: It ensures that JSON data is well-structured and adheres to defined rules. - **Documentation**: It serves as a clear specification for the expected format of data. - **Interoperability**: It provides a common framework for systems to exchange data reliably. ## Core Concepts -### JSON Data Types +### JSON data types JSON supports several basic data types that form the foundation for any schema: ### object @@ -49,12 +49,12 @@ JSON supports several basic data types that form the foundation for any schema: These types have [analogs in most programming languages](../understanding-json-schema/reference/type). -## The Role of a Schema +## The role of a schema A JSON Schema defines the structure and validation criteria for a given JSON document. It specifies which fields are required, the types of those fields, and any other constraints that must be met for the data to be considered valid. For instance, a schema for a `"Person"` might specify that it must contain a `first_name` and `last_name`, both of which should be strings. -Example Schema for a Person: +Example Schema for a person: ```` { @@ -69,44 +69,44 @@ Example Schema for a Person: ```` In this example: -- **`type`**: Defines the expected data type for the object. -- **`properties`**: Specifies the allowed properties of the object and their types. -- **`required`**: Lists the properties that must be included in the object. +- **type**: Defines the expected data type for the object. +- **properties**: Specifies the allowed properties of the object and their types. +- **required**: Lists the properties that must be included in the object. -### Writing a Simple JSON Schema +### Writing a simple JSON Schema To get started with JSON Schema, let’s begin with the simplest possible schema: one that accepts any valid JSON document. ##### Example: "Hello, World!" Schema -An empty schema (represented by `{}`) will validate any valid JSON data. +An empty schema (represented by `{}`) will validate any JSON data. -```json +``` // props { "isSchema": true } {} ``` This accepts anything, as long as it's valid JSON -```json +``` // props { "valid": true, "indent": true } 42 ``` -```json +``` // props { "valid": true, "indent": true } "I'm a string" ``` -```json +```` // props { "valid": true, "indent": true } { "an": [ "arbitrarily", "nested" ], "data": "structure" } ```` -## Restricting Data with the type Keyword +## Restricting data with the type keyword One of the most common tasks in JSON Schema is restricting data to a specific type. The type keyword allows you to enforce that a given field contains a specific kind of value. -Example: Enforcing a String Type +Example: Enforcing a string Type To ensure that the data is always a string, you can use the following schema: @@ -129,7 +129,7 @@ It will fail on non-string data: ```` -## Declaring a JSON Schema Version +## Declaring a JSON Schema version When defining a schema, it is good practice to specify which version of the JSON Schema specification the schema adheres to. This is done using the $schema keyword. @@ -143,10 +143,10 @@ Example: Declaring a Schema Version Although not mandatory, including $schema ensures that your schema is interpreted according to the correct version of the specification. -## Building a More Complex Schema +## Building a more complex schema As you create more sophisticated data structures, your schemas will become more complex. JSON Schema allows you to define nested objects and arrays, making it a powerful tool for managing structured data. -Example: Person with Address +Example: Person with address Consider a more detailed schema for a "Person" that includes an address field, which is itself an object with several properties @@ -175,11 +175,11 @@ In this schema: address is defined as an object with its own properties. The required keyword is used to ensure certain fields are present. -## Validating JSON Data Against a Schema +## Validating JSON data against a schema Once you have a schema, you can validate JSON data to ensure that it conforms to the expected structure. If the data is valid according to the schema, the validation will succeed; otherwise, it will fail. -Example: Valid Data +Example: Valid data This data conforms to the "Person with Address" schema: @@ -194,7 +194,7 @@ This data conforms to the "Person with Address" schema: } } ```` -##### Example: Invalid Data +##### Example: Invalid data This data is invalid because the city field is missing in the address object: @@ -209,13 +209,13 @@ This data is invalid because the city field is missing in the address object: } ```` -## Best Practices +## Best practices - **Use `$schema`**: Always declare which version of the JSON Schema specification you are using to avoid compatibility issues. - **Use `required` thoughtfully**: Specify which fields are essential for your data to ensure the validity of your documents. - **Provide clear documentation**: Use JSON Schema not just for validation, but also as a form of documentation to describe the structure of your data. -## Additional Resources +## Additional resources To deepen your understanding of JSON Schema, check out the following resources: