- Introduction
- Starting the schema
- Defining the properties
- Going deeper with properties
- Nesting data structures
- References outside the schema
- Taking a look at data for our defined JSON Schema
Introduction #
The following example is by no means definitive of all the value JSON Schema can provide. For this you will need to go deep into the specification itself – learn more at https://json-schema.org/specification.html.
Let’s pretend we’re interacting with a JSON based product catalog. This catalog has a product which has:
- An identifier:
productId - A product name:
productName - A selling cost for the consumer:
price - An optional set of tags:
tags.
For example:
{ "productId": 1, "productName": "A green door", "price": 12.50, "tags": [ "home", "green" ]}While generally straightforward, the example leaves some open questions. Here are just a few of them:
- What is
productId? - Is
productNamerequired? - Can the
pricebe zero (0)? - Are all of the
tagsstring values?
When you’re talking about a data format, you want to have metadata about what keys mean, including the valid inputs for those keys. JSON Schema is a proposed IETF standard how to answer those questions for data.
Starting the schema #
To start a schema definition, let’s begin with a basic JSON schema.
We start with four properties called keywords which are expressed as JSON keys.
Yes. the standard uses a JSON data document to describe data documents, most often that are also JSON data documents but could be in any number of other content types like
text/xml.
- The $schema keyword states that this schema is written according to a specific draft of the standard and used for a variety of reasons, primarily version control.
- The $id keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against.
- The title and description annotation keywords are descriptive only. They do not add constraints to the data being validated. The intent of the schema is stated with these two keywords.
- The type validation keyword defines the first constraint on our JSON data and in this case it has to be a JSON Object.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product in the catalog", "type": "object"}We introduce the following pieces of terminology when we start the schema:
- Schema Keyword:
$schemaand$id. - Schema Annotations:
titleanddescription. - Validation Keyword:
type.
Defining the properties #
productId is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn’t make sense to have a product without one, so it is required.
In JSON Schema terms, we update our schema to add:
- The properties validation keyword.
- The
productIdkey.descriptionschema annotation andtypevalidation keyword is noted – we covered both of these in the previous section.
- The required validation keyword listing
productId.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" } }, "required": [ "productId" ]}productNameis a string value that describes a product. Since there isn’t much to a product without a name it also is required.- Since the
requiredvalidation keyword is an array of strings we can note multiple keys as required; We now includeproductName. - There isn’t really any difference between
productIdandproductName– we include both for completeness since computers typically pay attention to identifiers and humans typically pay attention to names.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" } }, "required": [ "productId", "productName" ]}Going deeper with properties #
According to the store owner there are no free products. ;)
- The
pricekey is added with the usualdescriptionschema annotation andtypevalidation keywords covered previously. It is also included in the array of keys defined by therequiredvalidation keyword. - We specify the value of
pricemust be something other than zero using the exclusiveMinimum validation keyword.- If we wanted to include zero as a valid price we would have specified the minimum validation keyword.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "productId", "productName", "price" ]}Next, we come to the tags key.
The store owner has said this:
- If there are tags there must be at least one tag,
- All tags must be unique; no duplication within a single product.
- All tags must be text.
- Tags are nice but they aren’t required to be present.
Therefore:
- The
tagskey is added with the usual annotations and keywords. - This time the
typevalidation keyword isarray. - We introduce the items validation keyword so we can define what appears in the array. In this case:
stringvalues via thetypevalidation keyword. - The minItems validation keyword is used to make sure there is at least one item in the array.
- The uniqueItems validation keyword notes all of the items in the array must be unique relative to one another.
- We did not add this key to the
requiredvalidation keyword array because it is optional.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "productId", "productName", "price" ]}Nesting data structures #
Up until this point we’ve been dealing with a very flat schema – only one level. This section demonstrates nested data structures.
- The
dimensionskey is added using the concepts we’ve previously discovered. Since thetypevalidation keyword isobjectwe can use thepropertiesvalidation keyword to define a nested data structure.- We omitted the
descriptionannotation keyword for brevity in the example. While it’s usually preferable to annotate thoroughly in this case the structure and key names are fairly familiar to most developers.
- We omitted the
- You will note the scope of the
requiredvalidation keyword is applicable to the dimensions key and not beyond.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] } }, "required": [ "productId", "productName", "price" ]}References outside the schema #
So far our JSON schema has been wholly self contained. It is very common to share JSON schema across many data structures for reuse, readability and maintainability among other reasons.
For this example we introduce a new JSON Schema resource and for both properties therein:
- We use the
minimumvalidation keyword noted earlier. - We add the maximum validation keyword.
- Combined, these give us a range to use in validation.
{ "$id": "https://example.com/geographical-location.schema.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Longitude and Latitude", "description": "A geographical coordinate on a planet (most commonly Earth).", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }}Next we add a reference to this new schema so it can be incorporated.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "warehouseLocation": { "description": "Coordinates of the warehouse where the product is located.", "$ref": "https://example.com/geographical-location.schema.json" } }, "required": [ "productId", "productName", "price" ]}Taking a look at data for our defined JSON Schema #
We’ve certainly expanded on the concept of a product since our earliest sample data (scroll up to the top). Let’s take a look at data which matches the JSON Schema we have defined.
{ "productId": 1, "productName": "An ice sculpture", "price": 12.50, "tags": [ "cold", "ice" ], "dimensions": { "length": 7.0, "width": 12.0, "height": 9.5 }, "warehouseLocation": { "latitude": -78.75, "longitude": 20.4 } }FAQs
How to do a step-by-step guide? ›
- Name the process or task that you're describing and its purpose. ...
- Define the scope of work. ...
- Explain the inputs and outputs. ...
- Write down each step of the process you want to document. ...
- Order the steps. ...
- Describe how to complete each step.
- Use plain language.
- Be generous with italics and bold statements.
- User research can be a great source of knowledge.
- Your user feels confident.
- Write descriptive alt text for your images.
- Don't assume your user has prior knowledge.
A how-to guide is an instructional document that details a process from beginning to end through a string of step-by-step instructions. You'll usually find this type of guide online. Many people who read how-to guides want to understand or complete a task.
How many steps should a beginner start with? ›If you're a true beginner and completely new to exercise, Eric said to set your goal to something a little more realistic: 6,000 steps a day. "Then as you get into the habit and regularly hit your daily step target, increase this gradually toward 10,000-12,000 steps per day," he said.
What is the 10,000 steps method? ›Keep increasing the target by 1,000 steps every 28 days and you will reach 10,000 steps one day. This will take around 7-8 months from today if you start with 3,000 steps. But never miss a day.
What is in a quick start guide? ›- “What can this product do?”
- “How do I set this product up?”
- “What are my options with this product?”
- “Any cautionary notes before I begin using this product?”
A quick start guide, or QSG for short, focuses on the most common instructions, often accompanying such instructions with easy-to-understand illustrations. The appearance of a QSG can vary significantly from product to product and from manufacturer to manufacturer.
How do I create a user guide manual? ›- Define Your Audience. Know your reader—what is their experience level? ...
- Describe the Problem. ...
- Break it Down. ...
- Be Descriptive. ...
- Stick to the Topic at Hand. ...
- Take Awesome Photos (or Better Yet, Videos) ...
- Don't Use Passive Voice. ...
- Avoid Using the First Person.
- Keep it short and simple. All the information you jot down in your guide should be readable and readily accessible. ...
- Highlight important points with a different color. ...
- Include information on a need-to-know basis. ...
- Pay attention to the layout.
What is a resource guide? A resource guide is a list of the business solutions you recommend with a short description on what they are, how you are using them in your business, and why your audience will benefit from using them.
How do I create an online guide? ›
- Select the guide's page size. Create an account on Flipsnack and choose a size for your guide. ...
- Choose a guide template. ...
- Give your guide a personal touch by customizing it. ...
- Download and Print.
A tutorial teaches the audience a new idea or concept by showing how to accomplish a goal. Tutorials take you through a technical process step-by-step and tend to get straight to the point. A guide is usually focused on achieving a particular task and can assume some level of prerequisite knowledge.
What is the difference between a tutorial and a how do guide? ›A tutorial serves the needs of the user who is at study. Its obligation is to provide a successful learning experience. A how-to guide serves the needs of the user who is at work. Its obligation is to help the user accomplish a task.
Does walking reduce belly fat? ›Walking is a moderate-intensity exercise that can be easily incorporated into your daily life. Simply walking more often can help you lose weight and belly fat, as well as provide other excellent health benefits, including a decreased risk of disease and improved mood.
How many steps should an older person do? ›More specifically, for adults 60 and older, the risk of premature death leveled off at about 6,000-8,000 steps per day, meaning that more steps than that provided no additional benefit for longevity. Adults younger than 60 saw the risk of premature death stabilize at about 8,000-10,000 steps per day.
How many steps should a 60 year old take? ›Many experts agree that the recommended steps per day for seniors is 7,000-10,000. People who live with a disability or chronic illness can still benefit from an active lifestyle, and depending on individual abilities may strive for 5,500 steps per day.
Does walking in place count as steps? ›And walking in place TOTALLY counts. The secret to Housewalking is sneaking extra steps into your everyday life. Think of how often you sit throughout the day when you could be stepping!
How many steps a day to lose belly fat? ›If you're trying to lose weight or lose body fat, aim for 10,000 to 12,500+ steps a day.
How can I get 10,000 steps without leaving the house? ›- Shadow boxing. This isn't just about throwing your hands, but moving your feet to transfer power to your fists. ...
- Skipping. ...
- Work upstairs. ...
- Tea-break harder. ...
- Do It Yourself. ...
- Dancing. ...
- Live stream a workout. ...
- Craft a standing desk.
| Transfer Method | Data | Time |
|---|---|---|
| Restore from iCloud Backup | 64GB | 45 minutes - 1 hour |
| Restore backup from a computer(Mac or PC) using iTunes | 64GB | 10 - 20 minutes |
| Quick Start | 64GB | 45 minutes - 1 hour |
| MobileTrans | 64GB | 5 - 10 minutes |
What is quick start tool? ›
The Quick Start tool evaluates your model to determine the number of periodic sample rates in your system. Single rate. Your model has only one periodic sample rate. The generated code has a single-entry point function that runs at the time interval of the sample rate.
Why is a quick start guide important? ›A quick start guide gives the customer all the information they need to set up and use their new product or service properly. It can prevent confusion and improve the experience with a new product or service.
What is the first step in creating a quick part? ›The Quick Part Gallery is a list of phrases, sentences, or other text you've saved for easy access. To insert an item from the Quick Part Gallery, select Insert > Quick Parts and click on the item. It will be placed in your document at the point of the cursor.
What should be included in a user guide? ›- Product description content.
- Explanation of product features.
- Product installation and set up process.
- Product use cases.
- Potential product risks and how to solve them.
- Frequently Asked Questions (FAQs).
- Product demos, video tutorials and walkthroughs.
The User Manual contains all essential information for the user to make full use of the information system. This manual includes a description of the system functions and capabilities, contingencies and alternate modes of operation, and step-by-step procedures for system access and use.
How to write a user manual PDF? ›- Determine the purpose of your user manual.
- Thoroughly research the product.
- Draft workflows and a table of contents.
- Use a template or start from scratch.
- Review the final content and submit in PDF.
Key Difference: The term 'manual' or 'guide' both usually refer to a document whose main aim is to provide information or instructions. It is generally expected that guide are shorter, concise and more to the point than manual. A manual is expected to give more in-depth information and instruction than a guide.
What is difference between reference and guide? ›Ciz guide questions only have questions but on the other hand reference books have theory as well as questions.....
What is a reference guide called? ›The reference guide is sometimes called a data guide, interpretation guide, or interpretive guide.
What are the 7 steps for resource description? ›The process of describing resources consists of seven steps: Determining the scope and focus, determining the purpose, identifying resource properties, designing the description vocabulary, designing the description form and implementation, creating the descriptions, and evaluating the descriptions.
What are the three types of resource planning? ›
- Identification and inventory of resources. '
- Evolving a planning structure with appropriate technology, skill and institutional set-up for implementing resource development plans.
- Matching the resource development plans with overall national development plans.
- Determine required resources.
- Acquire resources.
- Manage resources.
- Control resource usage.
- Strategize your brand.
- Approach the design.
- Prioritize usability.
- Prepare for search engines.
- Professionalize your site.
- Optimize for mobile.
- Create compelling content.
- Maintain your site.
An interactive guide is an e-learning format and method used to engage users step-by-step in their handling of digital tools. With a digital adoption platform, this integrated functionality becomes an overlay on any web-based software or application. It guides users to perform actions or obtain information.
What are the different types of guide? ›- 1.1 Tour guide.
- 1.2 Mountain guide.
- 1.3 Wilderness guide.
- 1.4 Hunting guide.
- 1.5 Safari guide.
- 1.6 Fishing guide.
Project tutorials can be a great learning tool if you use them the right way. The wrong way would be to leap from tutorial to tutorial and not process what you just learned. You also don't want to develop a dependency on these tutorials and get trapped in tutorial hell.
What is a learning guide? ›A learning guide is a user manual about effective ways to learn the subject matter and skills in a course. Key features: Based on research in the learning sciences. Empirical research evidence informs the guide's strategies and suggestions about how to learn in the course.
What are the three parts of the tutorial process? ›The AVID tutorial process has been divided into three parts- before the tutorial, during the tutorial and after the tutorial. These three parts provide a framework for the 10 steps that need to take place to create effective, rigorous and collaborative tutorials.
What do you do during tutorials? ›What happens in tutorials? Unlike lectures, tutorials don't usually involve receiving information and taking notes. Tutes are usually structured according to the discipline. For example, a tutorial might be focussed around group discussions of key course topics or set reading material.
How do you structure a tutorial? ›- Preparation. Before your first tutorial, have a Meet the Tutor session to establish what your tutee needs and what the parent expects from the sessions. ...
- Starting the session. Build up trust and rapport with the student. ...
- Recap problem areas. ...
- Present a new skill or idea. ...
- Testing. ...
- Praise. ...
- Conclude.
What is a step by step guide called? ›
A step-by-step guide (also called a step-by-step instruction guide) outlines the steps required to complete a particular task.
What is another word for first step process? ›Some common synonyms of initiate are begin, commence, inaugurate, start, and usher in. While all these words mean "to take the first step in a course, process, or operation," initiate implies taking a first step in a process or series that is to continue.
What is a synonym for step by step approach? ›bit by bit. in stages. slowly but surely. one step at a time. inchmeal.
What is a step approach? ›N-step change models assume change does not occur without a planned, engineered, and managed mission. The basic idea is that the company has a stable but undesirable organisational situation, which needs to be altered. The stability must be dissolved in order to rearrange everything to a new desired, fixed situation.