docs: document the Test Suite

Author: josdejong

README.md

@@ -34,6 +34,7 @@ On this page:
 External pages:
 
 - [Function reference](reference/functions.md)
+- [Test Suite](test-suite/README.md)
 
 ## Installation
 
@@ -623,7 +624,9 @@ Another gotcha is that unlike some other query languages, you need to use the `m
 
 ## Development
 
-To develop, check out the repo, install dependencies once, and then use the following scripts:
+### JavaScript 
+
+To develop, check out the JavaScript repo, install dependencies once, and then use the following scripts:
 
 ```text
 npm run test
@@ -637,6 +640,12 @@ npm run build-and-test
 
 Note that a new package is published on [npm](https://www.npmjs.com/package/@jsonquerylang/jsonquery) and [GitHub](https://github.com/jsonquerylang/jsonquery/releases) on changes pushed to the `main` branch. This is done using [`semantic-release`](https://github.com/semantic-release/semantic-release), and we do not use the `version` number in the `package.json` file. A changelog can be found by looking at the [releases on GitHub](https://github.com/jsonquerylang/jsonquery/releases).
 
+### Implement in a new language
+
+Support for JSON Query language can be implemented in new programming languages. Implementing the query engine is most straight forward: this boils down to implementing each of the functions (`sort`, `filter`, `groupBy`, etc.), and creating a compiler which can go through a JSON Query like `["sort", ["get", "name"], "desc"]` look up the function `sort`, and pass the arguments to it. Implementing a parser and stringifier is a bit more work, but the parser and stringifier of the JavaScript implementation can be used as a reference.
+
+There is a JSON based Test Suite available that can be used to ensure that your implementation matches the behavior of the reference implementation, see: [Test Suite](test-suite/README.md). 
+
 ## Motivation
 
 There are many powerful query languages out there, so why the need to develop `jsonquery`? There are a couple of reasons for this.

test-suite/README.md

@@ -0,0 +1,34 @@
+# JSON Query Test Suite
+
+This test suite contains the reference tests for the JSON Query language in a language agnostic JSON format. These tests can be used to implement JSON Query in a new programming language or environment.
+
+The test-suite contains three sections:
+-   [`compile.test.json`](./compile.test.json) tests verifying the behavior of the compiler, the query engine, i.e.:
+
+    ```js
+    import { compile } from '@jsonquerylang/jsonquery'
+     
+    const queryIt = compile(["sort"])
+    const result = queryIt([3, 1, 5])
+    // result should be [1, 3, 5]
+    ```
+
+-   [`parse.test.json`](./parse.test.json) tests verifying the parser that parses the text format into the JSON format, i.e.:
+
+    ```js
+    import { parse } from '@jsonquerylang/jsonquery'
+     
+    const query = parse('filter(.age > 65)')
+    // query should be ["filter", ["gt", ["get", "age"], 65]]
+    ```
+
+-   [`stringify.test.json`](./stringify.test.json) tests converting the JSON format into the test format (including indentation), i.e.:
+
+    ```js
+    import { stringify } from '@jsonquerylang/jsonquery'
+     
+    const text = stringify(["sort", ["get", "age"], "desc"])
+    // text should be 'sort(.age, "desc")'
+    ```
+
+The test suites are accompanied by a `.d.ts` file containing the TypeScript models of the test suites, and a `.schema.json` file containing a JSON schema file matching the test suites. These can be of help when implementing a model for the test suites in a new language.