Introduction to JSON

What is JSON?

JSON (short for JavaScript Object Notation) is a syntax used to represent data structures in a simple, easy-to-read textual format. JSON is ubiquitous throughout the computing industry, and has become the de-facto data format of the Web.

If you have never seen JSON before, here is a small demonstration using JSON to describe a (fictional) person:

  "firstName": "Lando",
  "lastName": "Calrissian",
  "title": "Baron Administrator",
  "address": {
    "streetAddress": "123 Betrayal Dr",
    "city": "Cloud City",
    "planet": "Bespin"
  "homeworld": "Socorro",
  "currentLocation": null


There are many benefits to using JSON, some of which include:

  • It can be used to represent a wide array of objects in a simple and easy-to-read format, making it useful for just about anything

  • It is widely used and supported across web browsers and programming languages, making it very easy to develop for

  • It is easy to read and write by humans (as well as computers), making it a great choice for specifications like OpenAPI

  • It is a subset of another syntax called YAML. Documents written in JSON can also be written in YAML, so either format can be used to write OpenAPI specifications

  • It can be used to link files together through JSON references, making it easy to break up large documents into smaller, more focused documents

Whether you are modeling an API, creating a Prism Collection, or writing documentation in Stoplight, behind the scenes you are actually updating a JSON document.

You can see the underlying JSON document of any object being updated in Stoplight using the editor’s Code button at the top of the screen.

Related Articles