From 98926eb9e6245a7f6d21364cfedb4dc8645347cd Mon Sep 17 00:00:00 2001
From: James Prior <jamesgr.prior@gmail.com>
Date: Tue, 19 Sep 2023 08:44:35 +0100
Subject: [PATCH] docs: JSONPath syntax guide WIP

---
 docs/docs/guides/jsonpath-syntax.md           | 93 +++++++++++++++++--
 docs/docs/intro.mdx                           |  2 +-
 .../{cts.test.ts => normalized_path.test.ts}  |  0
 3 files changed, 85 insertions(+), 10 deletions(-)
 rename tests/path/{cts.test.ts => normalized_path.test.ts} (100%)

diff --git a/docs/docs/guides/jsonpath-syntax.md b/docs/docs/guides/jsonpath-syntax.md
index 87731a2..2b896af 100644
--- a/docs/docs/guides/jsonpath-syntax.md
+++ b/docs/docs/guides/jsonpath-syntax.md
@@ -1,26 +1,101 @@
 # JSONPath Syntax
 
-This page provides a casual introduction to JSONPath syntax described in the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20) specification. We follow it strictly and test against the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite).
+This page provides a casual introduction to JSONPath syntax described in the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20) specification. We follow it strictly, and test against the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite).
 
-TODO: intro
+Imagine a JSON document as a tree structure, where each JSON object and array can contain more objects, arrays and scalar values. Every object, array and scalar value is a node in the tree, and the outermost value is the "root" node.
 
-## Selectors and Identifiers
+Every query must start with either the root node identifier (`$`) or, within a [filter selector](#filters), the current node identifier (`@`). We then chain JSONPath _selectors_ together to retrieve nodes from the target document. Each selector operates on nodes matched by preceding selectors. What follows is a description of those selectors.
+
+:::info
+Strictly, using terminology from the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20), we chain _segments_, and those segments can contain _selectors_.
+
+We use the terms "target JSON document", "target document" and "query argument" interchangeably to mean the JSON value a query is applied to.  
+:::
+
+## Segments, Selectors and Identifiers
+
+```json title="Example JSON document"
+{
+  "users": [
+    { "name": "Sue", "score": 100 },
+    { "name": "John", "score": 86 },
+    { "name": "Sally", "score": 84 },
+    { "name": "Jane", "score": 55 }
+  ]
+}
+```
 
 ### Root (`$`)
 
-TODO:
+`$` is the root node identifier, pointing to the first node in the target JSON document.
 
-### Property names
+```text title="Example query"
+$.users
+```
 
-TODO:
+```json title="Example output"
+[
+  [
+    { "name": "Sue", "score": 100 },
+    { "name": "John", "score": 86 },
+    { "name": "Sally", "score": 84 },
+    { "name": "Jane", "score": 55 }
+  ]
+]
+```
+
+A query containing just the root identifier returns the target document in its entirety.
+
+### Property names (`['thing']`, `["thing"]` or `.thing`)
+
+Select an object's properties using dot notation (`.thing`) or within a [bracketed segment](#lists) (`['thing']` or `["thing"]`). Dot notation is only allowed if a property name does not contain reserved characters. These three queries are equivalent.
+
+```text
+$.users
+```
+
+```text
+$['users']
+```
+
+```text
+$["users"]
+```
+
+```json title="Example output"
+[
+  [
+    { "name": "Sue", "score": 100 },
+    { "name": "John", "score": 86 },
+    { "name": "Sally", "score": 84 },
+    { "name": "Jane", "score": 55 }
+  ]
+]
+```
 
 ### Array indices (`[0]` or `[-1]`)
 
-TODO:
+Select array items by their index. Indices are zero-based and must be enclosed in brackets. If the index is negative, items are selected from the end of the array.
 
-### Wildcard (`*`)
+```text title="The first user"
+$.users[0]
+```
 
-TODO:
+```text title="The last user"
+$.users[-1]
+```
+
+### Wildcard (`.*` or `[*]`)
+
+Select all items from an array or values from an object using the wildcard selector.
+
+```text
+$.users.*
+```
+
+```text
+$.users[*]
+```
 
 ### Slices (`[0:-1]` or `[-1:0:-1]`)
 
diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx
index 719c769..2c6328f 100644
--- a/docs/docs/intro.mdx
+++ b/docs/docs/intro.mdx
@@ -5,7 +5,7 @@ slug: /
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Introduction
+# JSON P3
 
 JSON P3 implements JSONPath following the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20) specification, JSON Pointer described by [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901), and JSON Patch described by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902).
 
diff --git a/tests/path/cts.test.ts b/tests/path/normalized_path.test.ts
similarity index 100%
rename from tests/path/cts.test.ts
rename to tests/path/normalized_path.test.ts