From 905ca386939645c6fa00d43374e4f6bb12a04d7d Mon Sep 17 00:00:00 2001
From: Ole Herman Schumacher Elgesem <ole@northern.tech>
Date: Tue, 26 Oct 2021 21:57:51 +0200
Subject: [PATCH] Added examples / explanation of JSON file format

This is what the file format should be, after we've made some
changes to merge index.json and cfbs.json.

Signed-off-by: Ole Herman Schumacher Elgesem <ole@northern.tech>
---
 JSON.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 JSON.md

diff --git a/JSON.md b/JSON.md
new file mode 100644
index 00000000..21f5ca59
--- /dev/null
+++ b/JSON.md
@@ -0,0 +1,178 @@
+# CFEngine Build JSON file format
+
+The CFEngine Build website and tooling relies on JSON files for different purposes;
+
+- The project file generated by running `cfbs` in your
+- The index of all available modules which is available on GitHub
+- A cfbs.json file with necessary metadata for adding a module using URL (not from index)
+
+All these 3 share 1 standard format, commonly called `cfbs.json`.
+
+(There is also [`versions.json`](https://github.com/cfengine/cfbs-index/blob/master/versions.json), but this specification is not about that file).
+
+## Keys
+
+`index`: URL, relative path, or inline dictionary.
+Used by `cfbs add` and `cfbs search`, when index key is present in `cfbs.json` in the current working directory.
+When adding a module by URL, which has a cfbs.json inside of it, the index in that file should be ignored.
+
+## Examples
+
+### New project
+
+Starting in an empty folder you can create a new project with the `init` command:
+
+```
+cfbs init
+```
+
+Which creates a file like this:
+
+```json
+{
+  "name": "Example",
+  "description": "Example description",
+  "type": "policy-set",
+  "build": []
+}
+```
+
+### Adding a module
+
+Continuing from the previous project, we can add a module:
+
+```
+cfbs add mpf
+```
+
+Which results in:
+
+```json
+{
+  "name": "Example",
+  "description": "Example description",
+  "type": "policy-set",
+  "build": [
+    {
+      "name": "masterfiles",
+      "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
+      "tags": ["official", "base", "supported"],
+      "repo": "https://github.com/cfengine/masterfiles",
+      "by": "https://github.com/cfengine",
+      "version": "0.1.1",
+      "commit": "5c7dc5b43088e259a94de4e5a9f17c0ce9781a0f",
+      "steps": [
+        "run ./autogen.sh",
+        "delete ./autogen.sh",
+        "run ./cfbs/cleanup.sh",
+        "delete ./cfbs/cleanup.sh",
+        "copy ./ ./"
+      ],
+      "added_by": "cfbs add"
+    }
+  ]
+}
+```
+
+## Alternate index
+
+You can start a project with an alternate index:
+
+```
+cfbs init --index blah
+```
+
+```json
+{
+  "name": "Example",
+  "description": "Example description",
+  "type": "policy-set",
+  "index": "blah",
+  "build": []
+}
+```
+
+`blah` can be a URL or a relative file path (inside project).
+
+## Index file
+
+The index file used by `cfbs` also follows the same format:
+
+```json
+{
+  "name": "Official CFEngine Build Index (default)",
+  "description": "File used by tooling and website to find modules",
+  "type": "index",
+  "index": {
+    "masterfiles": {
+      "description": "Official CFEngine Masterfiles Policy Framework (MPF)",
+      "tags": ["official", "base", "supported"],
+      "repo": "https://github.com/cfengine/masterfiles",
+      "by": "https://github.com/cfengine",
+      "version": "0.1.1",
+      "commit": "5c7dc5b43088e259a94de4e5a9f17c0ce9781a0f",
+      "steps": [
+        "run ./autogen.sh",
+        "delete ./autogen.sh",
+        "run ./cfbs/cleanup.sh",
+        "delete ./cfbs/cleanup.sh",
+        "copy ./ ./"
+      ]
+    }
+  }
+}
+```
+
+(Only showing 1 module here, the real file has many more).
+
+Note that it is reusing the `index` key, but this time with a dictionary (inline index).
+
+## A separate repo which provides modules
+
+If you put your modules in a repo and don't have them in the index (yet), you can use the `provides` key:
+
+```json
+{
+  "name": "Example module in separate repo",
+  "description": "Example description",
+  "type": "module",
+  "provides": {
+    "example-module": {
+      "name": "example-module",
+      "description": "Just an example",
+      "tags": ["local"],
+      "version": "1.0.0",
+      "dependencies": ["autorun"],
+      "steps": ["copy ./test.cf services/autorun/test.cf"],
+      "added_by": "cfbs add"
+    }
+  }
+}
+```
+
+## Adding a module from repo URL
+
+```
+cfbs init && cfbs add https://github.com/cfengine/some-repo
+```
+
+```json
+{
+  "name": "Example",
+  "description": "Example description",
+  "type": "policy-set",
+  "build": [
+    {
+      "name": "example-module",
+      "description": "Just an example",
+      "tags": ["local"],
+      "repo": "https://github.com/cfengine/some-repo",
+      "version": "1.0.0",
+      "commit": "be3bc015f6a19e945bb7a9fa0ed78c97e2cecf61",
+      "dependencies": ["autorun"],
+      "steps": ["copy ./test.cf services/autorun/test.cf"],
+      "added_by": "cfbs add"
+    }
+  ]
+}
+```