Updates to JSON Introduction (#162)

* Updates to JSON intro

* Fix link, remove callout annotation

* Update json-introduction.md

articles/modeling/json-introduction.md

@@ -1,25 +1,63 @@
-# Introduction to Objects in API Document Structure 
+# Introduction to JSON
 
-- An OpenAPI document is a document that describes an API and conforms to the OpenAPI Specification. These documents can be in YAML or JSON format. 
-- Your OpenAPI document can be a single document or a combination of several associated resources which use the $ref syntax to reference the interrelated resources. 
+## What is JSON?
 
-## Primitive Data Objects Supported in an OpenAPI Document
+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.
 
-- integer (int32 and int64)
-- number (float and double) 
-- string 
-- byte
-- binary 
-- boolean 
-- date
-- dateTime
-- password 
+If you have never seen JSON before, here is a small demonstration using JSON to
+describe a (fictional) person:
 
-## Additional OpenAPI Objects 
+```json
+{
+  "firstName": "Lando",
+  "lastName": "Calrissian",
+  "title": "Baron Administrator",
+  "address": {
+    "streetAddress": "123 Betrayal Dr",
+    "city": "Cloud City",
+    "planet": "Bespin"
+  },
+  "homeworld": "Socorro",
+  "currentLocation": null
+}
+```
 
-- **Info Object**: describes the API's title, description (optional), and version metadata. It also supports other details such as contact information, license, and terms of service. 
-- **Server Object**: identifies the API server and base URL. You can identify a single server or multiple servers and describe them using a description field. All API paths are relative to the URL of the server, for example, "/pets" when fully dilineated, may describe "http://api.hostname.com/pets." 
-- **Paths Object**: outlines relative paths to individual endpoints within your API and the operations or HTTP methods supported by the endpoints. For example, "GET/pets" can be used to return a list of pets. 
-- **Parameter Object**: describes a single operation parameter. Operations can have parameters passed through by several means such as: URL path, query string, cookies, and headers. Parameters can be marked as mandatory or optional, you can also describe the format, data type, and indicate its depreciation status. 
-- **Request body object**: describes body content and media type. It is often used with insert and update operations (POST, PUT, PATCH).
-- **Response object**: describes the expected response which can be referenced using the $ref syntax or described within the document. It associates an HTTP response code to the expected response. Examples of HTTP status codes incldue the 200-OK or 404-Not Found codes. [Click here for more information on HTTP Response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
+## Why JSON?
+
+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](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification)
+
+* It is a subset of another syntax called
+  [YAML](https://en.wikipedia.org/wiki/YAML). Documents written in JSON can also
+  be written in YAML, so either format can be used to write OpenAPI documents
+
+* It can be used to link files together through [JSON
+  references](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec), 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**
+
+* [JSON Overview - Wikipedia](https://en.wikipedia.org/wiki/JSON)
+* [YAML Overview - Wikipedia](https://en.wikipedia.org/wiki/YAML)
+* [OpenAPI Specification Format Reference](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#format)
+* [Referencing Another API Specification](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec)