General

JSON

JSON (JavaScript Object Notation) is a text-based serialization, originally for JavaScript but which has become popular for a variety of languages. It is self-describing, relatively simple but expressive enough for many constructs of many programming languages. It is organised as a collection of name/value pairs, possibly nested. Arrays of comma separated values are included. A formal description of the data types is at Introducing JSON

The example used earlier was this: suppose we have data about a person and their email addresses. Informally it could look like this

Name {
    string family
    string personal
}

Email {
    string kind
    string address
}

Person {
    Name name
    Email[] emails
}
      

An example could be

Person {
    Name: {
              family: "Newmarch"
              personal: "Jan"
          }
    Email[]: {
              Email: {
                        kind: "home"
                        address: "jan@newmarch.name"
                     }
              Email: {
                        kind: "work"
                        address: "j.newmarch@boxhill.edu.au"
                     }
             }
}
      

A JSON description of a person would look like

{
   "name": {
              "family": "Newmarch",
              "personal": "Jan"
          },
    "email": [
              {
                        kind: "home",
                        address: "jan@newmarch.name"
              },
              {
                        kind: "work",
                        address: "j.newmarch@boxhill.edu.au"
              }
    ]
}
      

JSON is decribed as an ECMA standard The JSON Data Interchange Syntax and an IETF standard at RFC 7159 .

Most languages now have libraries to convert between a JSON string and a data structure in that language.

JSON Schemas

The ECMA description of JSON does not include any schema language. So for each API you find, there will be a mapping between the data types of that language and the JSON data that you have. Not a good situation, as you will have to try to build a data type in your language, convert an example to JSON and see if it agrees with your example case.

A schema definition allows you to specify what the JSON data type should look like. Hopefully, tools will then allow you to generate language-specific code to handle it.

The primary JSON schema type is, predictably, called JSON Schema: A Media Type for Describing JSON Documents and has its home site at JSON Schema .

A schema suitable for the example discussed is

{
    "$schema": "http://json-schema.org/draft/2019-09/schema",
    "title": "Person",
    "type": "object",
    "required": ["name", "email"],
    "properties": {
	"name": {
	    "type": "object",
	    "properties": {
		"personal": {
		    "type": "string"
		},
		"family": {
		    "type": "string"
		}
	    }
	},
	
	"email": {
	    "type": "array",
	    "items": {
		"type":"object",
		"properties": {
		    "kind": {
			"type": "string"
		    },
		    "address": {
			"type": "string"
		    }
		}
	    }
	}
    }
}
      

How did I get to this? By following the spec and looking at examples at Miscellaneous Examples, and trying things. I validated them using the fantastic validator and corrected my schema until I got it right.

The value of a schema is that it should allow tools to be built that will allow generation of code for that specific schema instance, making it easier to build and manage instances of that type.

Resources

• JSON Schema: Implementations

---

Copyright © Jan Newmarch, jan@newmarch.name

" Network Programming using Java, Go, Python, Rust, JavaScript and Julia" by Jan Newmarch is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License .
Based on a work at https://jan.newmarch.name/NetworkProgramming/ .

If you like this book, please contribute using PayPal