Document schemas (#121)

peter-evans · Jan 11, 2022 · bd17347 · bd17347
1 parent 79e27f6
commit bd17347
Show file tree

Hide file tree

Showing 5 changed files with 164 additions and 0 deletions.
diff --git a/docs/docs/cmd/apply.md b/docs/docs/cmd/apply.md
@@ -63,6 +63,21 @@ cat topics/my_topic.yml | kdef apply - --dry-run
     Implies `--quiet` and outputs JSON apply results.
     The default value is `false`.
 
+    Schema:
+    ```js
+    [
+        {
+            "local": object, // local definition
+            "remote": object, // remote definition
+            "data": null|object, // additional data
+            "diff": string,
+            "error": string,
+            "applied": bool
+        }
+    ]
+    ```
+    For definition and additional data schemas see the documentation for each definition.
+
 - **--continue-on-error / -c** (bool)
 
     Applying resource definitions is not interrupted if there are errors.

diff --git a/docs/docs/def/acl.md b/docs/docs/def/acl.md
@@ -87,3 +87,37 @@ A group of ACL entries, where specifying more than one value for its properties
 ```yml
 --8<-- "examples/definitions/acl/topic/store.events.order-created.yml"
 ```
+
+## Schema
+
+**Definition:**
+```js
+{
+    "apiVersion": string,
+    "kind": string,
+    "metadata": {
+        "name": string,
+        "type": string,
+        "labels": [
+            string
+        ]
+    },
+    "spec": {
+        "acls": [
+            {
+                "hosts": [
+                    string
+                ],
+                "operations": [
+                    string
+                ],
+                "permissionType": string,
+                "principals": [
+                    string
+                ]
+            }
+        ],
+        "deleteUndefinedAcls": bool
+    }
+}
+```
diff --git a/docs/docs/def/broker.md b/docs/docs/def/broker.md
@@ -43,3 +43,25 @@ A definition representing a single specified Kafka broker.
 ```yml
 --8<-- "examples/definitions/broker/1.yml"
 ```
+
+## Schema
+
+**Definition:**
+```js
+{
+    "apiVersion": string,
+    "kind": string,
+    "metadata": {
+        "name": string,
+        "labels": [
+            string
+        ]
+    },
+    "spec": {
+        "configs": {
+            string: string
+        },
+        "deleteUndefinedConfigs": bool
+    }
+}
+```
diff --git a/docs/docs/def/brokers.md b/docs/docs/def/brokers.md
@@ -42,3 +42,25 @@ A definition representing cluster-wide configuration for all Kafka brokers.
 ```yml
 --8<-- "examples/definitions/brokers/store-cluster.yml"
 ```
+
+## Schema
+
+**Definition:**
+```js
+{
+    "apiVersion": string,
+    "kind": string,
+    "metadata": {
+        "name": string,
+        "labels": [
+            string
+        ]
+    },
+    "spec": {
+        "configs": {
+            string: string
+        },
+        "deleteUndefinedConfigs": bool
+    }
+}
+```
diff --git a/docs/docs/def/topic.md b/docs/docs/def/topic.md
@@ -154,3 +154,74 @@ In particular, partition leaders (the first replica in the assignment) are evenl
 ```yml
 --8<-- "examples/definitions/topic/store.events.order-dispatched.yml"
 ```
+
+## Schema
+
+**Definition:**
+```js
+{
+    "apiVersion": string,
+    "kind": string,
+    "metadata": {
+        "name": string,
+        "labels": [
+            string
+        ]
+    },
+    "spec": {
+        "configs": {
+            string: string
+        },
+        "deleteUndefinedConfigs": bool,
+        "partitions": int,
+        "replicationFactor": int,
+        "assignments": [
+            [
+                int
+            ]
+        ],
+        "managedAssignments": {
+            "rackConstraints": [
+                [
+                    string
+                ]
+            ],
+            "selection": string,
+            "balance": string
+        },
+        "maintainLeaders": bool
+    },
+    "state": {
+        "assignments": [
+            [
+                int
+            ]
+        ],
+        "leaders": [
+            int
+        ]
+    }
+}
+```
+
+**Additional Data:**
+
+The following additional data is output with the apply result when using the `--json-output` option.
+```js
+{
+    "partitionReassignments": null|[
+        {
+            "partition": int,
+            "replicas": [
+                int
+            ],
+            "addingReplicas": null|[
+                int
+            ],
+            "removingReplicas": null|[
+                int
+            ]
+        }
+    ]
+}
+```