From 015657b31dd2da14b786086ffe612e7c690833db Mon Sep 17 00:00:00 2001
From: tb06904 <141412860+tb06904@users.noreply.github.com>
Date: Wed, 13 Sep 2023 16:17:18 +0000
Subject: [PATCH] add JSON info page

---
 docs/user-guide/gaffer-basics/what-is-json.md | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/docs/user-guide/gaffer-basics/what-is-json.md b/docs/user-guide/gaffer-basics/what-is-json.md
index e69de29bb2..95f19af6ba 100644
--- a/docs/user-guide/gaffer-basics/what-is-json.md
+++ b/docs/user-guide/gaffer-basics/what-is-json.md
@@ -0,0 +1,92 @@
+# What is JSON?
+
+JavaScript Object Notation is a commonly used data format used for storing and
+transporting data; notably the industry standard for modern web requests. It's
+constructed of a set of key value pairs as exampled:
+
+```json title="JSON Example"
+{
+    "name": "example name",
+    "team": "example team",
+    "interests": ["stuff", "more stuff"],
+    "pets": 2,
+    "location": {
+        "country": "GB",
+        "region": "somewhere"
+    },
+    "present": true,
+    "appendices": null
+}
+```
+
+!!! note ""
+
+    For further reading on JSON please see the [official website](https://www.json.org/json-en.html).
+
+## JSON Data Types
+
+JSON objects are defined by the contents of a pair of braces: `{}`, these then
+contain the various comma separated key value pairs that make up a block of data
+to be stored or transported. JSON has a number of supported data types and some
+notable exceptions.
+
+### Supported Data Types
+
+- **Strings** - A simple string of characters e.g. `"A String"`.
+- **Numbers** - Number representations, mostly compliant with ISO 6093 with a
+  few exceptions that we won't go into here.
+- **Objects** - Nested JSON object e.g. the `"location"` object in the example.
+- **Arrays** - A list of entries, denoted by `[]` e.g. `"interests"` in the
+  example.
+- **Booleans** - `true` or `false` values e.g. `"present"` in the example.
+- **Null** - Represents no value e.g. `"appendices"` in the example.
+
+### Unsupported Data Types
+
+- **Dates** - There is no inbuilt date standard for JSON, most people use a
+  `String` to represent a date value.
+- **Undefined** - Undefined is a special state where something does not exist,
+  this is different to in concept to null.
+
+## How is JSON Used in Gaffer?
+
+JSON in Gaffer is largely used as an interchange format for data and can be found
+mainly in the API but also in many configuration files. The following sections
+give a quick introduction as to where and how JSON is used in Gaffer.
+
+### JSON in the Gaffer API
+
+Gaffer provides a number of communication methods so that you can
+programmatically interact with a graph, as of Version 2.0 this is provided in 3
+ways: A HTTP rest API, a Python API and a Native Java interface. Of these 3 both the
+Python and rest API use JSON as their method of data transportation, although
+the Python API obfuscates JSON behind the `gafferpy` client library.
+
+Here is an example of the structure of an operations request using JSON via the
+rest API:
+
+```json
+{
+    "class": "OperationChain",
+    "operations": [
+        {
+            "class": "GetAllElements"
+        },
+        {
+            "class": "Count"
+        }
+    ]
+}
+```
+
+### JSON in Gaffer configs
+
+Gaffer also utilises JSON as a method of storing configuration data for the
+graph, the most notable area of this being the Gaffer schema. A full break down
+of the Gaffer schema can be found in the [graph schema guide](../schema.md).
+
+Other notable configuration files are:
+
+- `graphConfig.json` - The main graph configuration file.
+- `operationsDeclarations.json` - Used to activate additional operations for use
+  in the graph.