It has happened to me many times that issues discussed and re-discussed a million times, came back into vogue as doubts, perhaps trivial but always dangerous, being able to give rise to unknown outputs.
I’m talking about the very useful JSON (JavaScript Object Notation) format, often useful in case of Ajax communications with a server but often also in other different situations.
The raison d’être of this meta-language is to allow the exchange of information between even very different interlocutors, almost as if it were a universal language.
When it comes to REST architecture it is perhaps one of the most used languages for data exchange.
In the associated headers of the JSON it is mandatory to insert the following:
Content-Type: application/json
This format has long replaced the old XML format, which is much more verbose and therefore less efficient in passing data over the internet. Furthermore, XML is more of a markup language, dedicated to other purposes, while JSON was born for what it is used for.
Valid types in JSON are as follows:
- single
null
value. - boolean: can be only
true
orfalse
. You can use it for binary “flag” properties (on/off). - number: can be an integer (
12323
) or decimal (3.14
) value. Can’t insert alphabetical characters inside this type of property, only numeric. - string: all it is between double quotes (
"
). Can’t use single quotes to define a string but you can use'
like character inside it. If you have to use double quotes inside a string type property you can prepend a back slash\
first of the character"
. - array: can be of every value type (boolean, number, string, objects or other arrays), between in square brackets
[]
. If you need non-numeric index lists you can use an object type. - object: (also called associative arrays) all between curly brackets
{}
. It can have only string properties keys but every type of value (boolean, number, string, array or other objects).
One thing that many people often ignore is that there is no special data type for dates. Dates trivially pass through the string type, in an arbitrarily chosen format. Other special formats (such as dates just mentioned) are entered as a string.
An example of these formats:
{
"aNull": null,
"aBoolean": true,
"anIntegerNumber": 23424,
"aDecimalNumber": 0.4,
"aString": "Lorem ipsum",
"aStringDate": "2030-12-14",
"anArray": ["Lorem", 234, 0.6],
"anObject": {"aProperty": 34},
"aDateString": "10-12-1492"
}
You can see its origin from javascript precisely for Javascript Object literals. Compared to them, however, JSON has some more restrictions.
Some of these restrictions:
- The keys and the string values inside the objects must necessarily have double quotes (
"
). You cannot insert a property in an object that is not delimited by double quotes. - You cannot insert functions or lampda as property values. A work-around to this limitation is to insert a function like of string type.
- It is not possible to create a list
[]
with textual or non-numeric indexes. A good work-around to this limitation is to use an object type like an array. The order that will be followed is that in which the properties within the object are presented. - As already mentioned, there is no
date
format to use. This is also more generally true for any new object instance you want to initialize within the properties of a json object. The underlying reason is that the json format does not have an engine behind it that makes certain basic objects available, as is the case for other languages.
It is therefore not allowed to insert syntax of the typenew Date ()
. - Comments cannot be entered anywhere. All languages allow you to insert comments into the code (CSS:
/* */
, Java/Javascript:/* */
or//
, HTML:<!-- -->
, etc.) but the json is designed to pass the bare essentials of information and therefore avoid inserting decorations that would be useful for the developer who puts his hand to it but are considered a waste of bandwidth when it comes to this format. To overcome this lack there are tools made on purpose to explain what a given system exposes in json format. I’m thinking for example of Swagger, a library dedicated to this purpose. - Variables initialized elsewhere in the code cannot be retrieved.
The key reason for these limitations is that JSON, although born as a javascript format, must connect multiple languages and therefore you cannot stray too far from a shared standard that resembles as many languages as possible. Let’s take as an example a server based on Java language that has to deliver information to a FE on frameworks like Angular / React. Compared to those frameworks, Java offers many more features and data structures that could not be read by another language. Even the simplest syntaxes often differ (see arrow function vs lambda).
The following is not the json format but a generic javascript object:
const anExternalVariable = 'anExternalValue';
const anObject = {
aString: 'a javascript string with "',
anArrowFunction: () => {},
anotherString: `another javascript string`,
// a comment
aDate: new Date(),
anImplicitFunction: (aVariable === 0),
anExternalVariable: anExternalVariable,
};
As you can see:
- Strings have unexpected delimiting characters.
- The anonymous functions are in a strictly Javascript format.
- There are comments
- Object instances that JSON cannot know are initialized.
- Variables external to the object are called.
When providing information in json format, it is always a good idea to avoid another type of data coming out, for instance an HTML 404 page instead of a json object. This is important to remember for example when handling error conditions. In those cases you have to make sure that some object comes out starting and ending with a brace in order not to cause unexpected errors on the FE that it cannot handle.
While previously json reigned supreme also as a use for configuration files, in the latter the use of the yaml format is preferred for those. This is an indentation-based format.