JSON Structure and Schema

I am sure you are familiar with JSON Structure – JSON stands for Javascript Object Notation. Some people say JSON notation but even though I don’t think it is wrong, the double notation doesn’t look good -. You see it everywhere. I am not so sure you are familiar with JSON Schema. This post meant to be read by everyone, not just beginners. I write it to people who are ready to feel like beginners.

Why do we need to learn JSON?

Maybe 15 years ago, when the ASP programmers were ubiquitous, XML (eXtensible Markup Language) responses were popular. XML is still popular of course, but I see JSON a lot more probably because I examine Javascript and Python systems.

Because of this familiarity, like the words you learned from people but not from the dictionary, you may think you know JSON, or maybe you are a beginner and you know that you don’t know JSON.

I realized I don’t know JSON in a programming assessment for a job application. The question was “What is the proper content type for JSON from the below answers?”. I was very confident and looking for application/json but couldn’t see it. Instead, I saw application/vnd.api+json(won’t be covered in this post but next) and I told myself “Obviously that is the answer but what(the f) is that?” and saw there is a whole new world of JSON out there.

JSON Structure

Let’s start at the very beginning. As the name implies, JSON is object notation in Javascript but actually, there are slight differences. The root of the JSON Response or Request is wrapped either in curly brackets or square brackets. Curly brackets

I think capital letters at the beginning of the words took your attention. This way of writing, starting every word with a capital letter except the first word, is called camelCase.

What is a Number?

In different languages, there are usually integer data structures. There also some integer data structures in Javascript too but the most generic usage which you will use in your JSON Document will have a Number data structure.

A Number’s key is double-quoted but not its value.

{
"aString": "Some text",
"aNumber": 10
}

A number can have a floating-point number.

{
"aFloatingPointNumber": 3.1415,
"anExponentional": 8.15e6
}

But an integer can’t(There is no distinct integer type other than a number in JSON Structure, there is in JSON Schema). Also, numbers in double-quotes are interpreted as strings, not numbers.

What is an Object?

An Object in JSON Structure, as we mentioned before, a map of key and value pairs. Every other property type can exist as a property in an Object.

Nested Objects

Nested objects are objects as values of a key in an upper-level object. Here is one:

What is null?

Null is simply the absence of a value.

We Learned JSON

Now go back to the first populated JSON object and array examples and enjoy understanding them. I created examples with Mockaroo, you can create any amount of any JSON Structure with mock data you want with it. The free plan is limited to 1000 records and there are also many other types like XML and CSV if you are C# or a Python developer.

I want to show you an example of JSON usage in a CRUD(Create Read/Retrieve Update Delete) application. I think going so theoretical won’t burn this topic into your memory.

Our Node.js server application will get some data in JSON format from the client/browser and respond with processed data. It will be a letterbox. It will receive, keep and show letters sent to it.

I will use the curl application for making requests from the Linux Subsystem Shell in Windows. Our JSON request to the server will look like this:

But will everyone be good-willed like you? What if we put a number to username property in our JSON request? JSON requests and responses must be validated, not just for security but also for having a standard. Let’s learn about how to annotate structures for our JSON documents.

JSON Schema

JSON Schema, by its own words, is a media type for validating and annotating JSON documents. We saw the issue of validating in our Javascript CRUD example and will see in other projects in the future too, validation is something you should always do. Annotation lays down the template for documents, providing a good understanding of them. A good understanding of templates of the documents is required for obeying to a standard. Obeying to a standard is important for consistency in code and preventing conflicts in usage in the future. Also, our code has to be self-documented so annotation plays a part in it too.

We will explore the JSON Schema in this section. I won’t cover hyper-media now. We will cover it and other API specifications in another article. I want to give you a glance at how to construct schemas. Otherwise, JSON Schema has great and easy documentation so it would be copying it to the blog post.

First, identify what data structures we have. We have integers at pet[].leg_count and car.year properties. first_name, last_name, car.make and car.model are ordinary string properties(make and model options are much so we will approach them as ordinary strings). email is a string property with a pattern, as well as ip_address. gender is a string with a limited number of value options. pets is an array of objects with a template consists of species and leg_count properties.

We set an id for later usage of schema, indicated that this JSON is a schema by setting $schema, put a descriptive title and set the type. There are several values type property can take, we will discover them in our steps. Let’s fill our JSON schema.

What do we do for ordinary strings?

We have ordinary strings – by ordinary I mean strings don’t have patterns – in root object and car nested object. we need to add these lines to the root object:

Patterns in Strings

With pattern property, validators use our schema will check the email property in the request that it is an email or not. Of course, this pattern is a little bit wrong because of its extreme simplicity. If you want a complete solution you can check RFC 822 and email regex. There is also a possibility of doing this according to RFC 5322, section 3.4.1:

Email is required because it is the only unique property, it is not a must, just an arbitrary choice to show you that functionality. We defined the pets array’s items in the same document but we could also migrate definition to a different file and import it from there.

I kept it simple. Schema can get complex, I can make another mini-post if you would like to. Next post will be about API specifications like HAL, JSON:API and JSON Schema’s hyper-media. If you want to ask something or just say your good wishes, don’t forget to comment. You can share the post with others if you think they will benefit. Also, you can subscribe by clicking here for more well-thought and unique content. I wish you a fun day.