feat: display schema for dfx metadata json (#3705)

* dfx schema for dfx-metadata

* include dfx-metadata-schema.json

* update workflow

* changelog and doc

* display

* e2e tests

.github/workflows/update-docs.yml

@@ -37,14 +37,17 @@ jobs:
         run: |
           cargo run -- schema --outfile docs/dfx-json-schema.json
           cargo run -- schema --for networks --outfile docs/networks-json-schema.json
+          cargo run -- schema --for dfx-metadata --outfile docs/dfx-metadata-schema.json
           echo "dfx.json schema:"
           cat docs/dfx-json-schema.json
           echo "networks.json schema:"
           cat docs/networks-json-schema.json
+          echo "dfx-metadata schema:"
+          cat docs/dfx-metadata-schema.json
           if [[ $(git status | wc -l) -eq 2 ]]; then
             git config user.name "GitHub Actions Bot"
             git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git add docs/dfx-json-schema.json docs/networks-json-schema.json
+            git add docs/dfx-json-schema.json docs/networks-json-schema.json docs/dfx-metadata-schema.json
             git commit -m "update dfx-json-schema and networks-json-schema" || true
             git push
           fi

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 # UNRELEASED
 
+### feat: display schema for dfx metadata json
+
+`dfx schema --for dfx-metadata` to display JSON schema of the "dfx" metadata.
+
 ### feat: add tech_stack to the Canister Metadata Standard
 
 The standardized `dfx` metadata is extended with another object: `tech_stack`.

docs/cli-reference/dfx-schema.mdx

@@ -16,10 +16,10 @@ dfx schema [option] [flag]
 
 You can use the following option with the `dfx schema` command.
 
-| Option                 | Description                                                                                                       |
-|------------------------|-------------------------------------------------------------------------------------------------------------------|
-| `--for <dfx/networks>` | Display schema for either dfx.json or networks.json. (default: dfx) |
-| `--outfile <outfile>`  | Specifies a file to output the schema to instead of printing it to stdout. |
+| Option                 | Description                                                                                      |
+|------------------------|--------------------------------------------------------------------------------------------------|
+| `--for <dfx/networks>` | Display schema for which JSON file. (default: dfx, possible values: dfx, networks, dfx-metadata) |
+| `--outfile <outfile>`  | Specifies a file to output the schema to instead of printing it to stdout.                       |
 
 ## Examples
 
@@ -35,6 +35,12 @@ You can print the schema for `networks.json` by running the following command:
 dfx schema --for networks
 ```
 
+You can print the schema for the "dfx" metadata JSON (which contains fields such as "pullable", "tech_stack", etc) by running the following command:
+
+``` bash
+dfx schema --for dfx-metadata
+```
+
 If you want to write the schema for dfx.json to `path/to/file/schema.json`, you can do so by running the following command:
 
 ``` bash

docs/dfx-metadata-schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "\"dfx\" metadata.",
+  "description": "Standardized metadata for dfx usage.",
+  "type": "object",
+  "properties": {
+    "pullable": {
+      "title": "Pullable",
+      "description": "The required information so that the canister can be pulled using `dfx deps pull`.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/Pullable"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "tech_stack": {
+      "title": "Tech Stack",
+      "description": "The tech stack information of the canister.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/TechStack"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "Pullable": {
+      "type": "object",
+      "required": [
+        "dependencies",
+        "init_guide",
+        "wasm_url"
+      ],
+      "properties": {
+        "dependencies": {
+          "title": "dependencies",
+          "description": "Canister IDs (Principal) of direct dependencies.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "init_arg": {
+          "title": "init_arg",
+          "description": "A default initialization argument for the canister that consumers can use.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "init_guide": {
+          "title": "init_guide",
+          "description": "A message to guide consumers how to initialize the canister.",
+          "type": "string"
+        },
+        "wasm_hash": {
+          "title": "wasm_hash",
+          "description": "SHA256 hash of the wasm module located at wasm_url. Only define this if the on-chain canister wasm is expected not to match the wasm at wasm_url. The hash can also be specified via a URL using the `wasm_hash_url` field. If both are defined, the `wasm_hash_url` field will be ignored.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "wasm_hash_url": {
+          "title": "wasm_hash_url",
+          "description": "Specify the SHA256 hash of the wasm module via this URL. Only define this if the on-chain canister wasm is expected not to match the wasm at wasm_url. The hash can also be specified directly using the `wasm_hash` field. If both are defined, the `wasm_hash_url` field will be ignored.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "wasm_url": {
+          "title": "wasm_url",
+          "description": "The Url to download canister wasm.",
+          "type": "string"
+        }
+      }
+    },
+    "TechStack": {
+      "title": "Tech Stack",
+      "description": "The tech stack used to build a canister.",
+      "type": "object",
+      "properties": {
+        "cdk": {
+          "title": "cdk",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        },
+        "language": {
+          "title": "language",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        },
+        "lib": {
+          "title": "lib",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        },
+        "other": {
+          "title": "other",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        },
+        "tool": {
+          "title": "tool",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

e2e/tests-dfx/schema.bash

@@ -22,3 +22,17 @@ teardown() {
   echo '{}' | jq '.broken_key="blahblahblah"' > dfx.json
   assert_command dfx schema
 }
+
+@test "dfx schema can display for networks" {
+  assert_command dfx schema --for networks --outfile out.json
+  # make sure out.json contains exactly one json object
+  assert_command jq type out.json
+  assert_eq '"object"'
+}
+
+@test "dfx schema can display for dfx-metadata" {
+  assert_command dfx schema --for dfx-metadata --outfile out.json
+  # make sure out.json contains exactly one json object
+  assert_command jq type out.json
+  assert_eq '"object"'
+}

src/dfx/src/commands/schema.rs

@@ -1,4 +1,4 @@
-use crate::lib::error::DfxResult;
+use crate::lib::{error::DfxResult, metadata::dfx::DfxMetadata};
 use anyhow::Context;
 use clap::{Parser, ValueEnum};
 use dfx_core::config::model::dfinity::{ConfigInterface, TopLevelConfigNetworks};
@@ -9,6 +9,7 @@ use std::path::PathBuf;
 enum ForFile {
     Dfx,
     Networks,
+    DfxMetadata,
 }
 
 /// Prints the schema for dfx.json.
@@ -25,6 +26,7 @@ pub struct SchemaOpts {
 pub fn exec(opts: SchemaOpts) -> DfxResult {
     let schema = match opts.r#for {
         Some(ForFile::Networks) => schema_for!(TopLevelConfigNetworks),
+        Some(ForFile::DfxMetadata) => schema_for!(DfxMetadata),
         _ => schema_for!(ConfigInterface),
     };
     let nice_schema =

src/dfx/src/lib/metadata/dfx.rs

@@ -5,12 +5,13 @@
 use crate::lib::{builders::command_output, error::DfxResult};
 use anyhow::{bail, Context};
 use dfx_core::config::model::dfinity::{Pullable, TechStack, TechStackCategoryMap};
+use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::path::Path;
 
 /// # "dfx" metadata.
 /// Standardized metadata for dfx usage.
-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
 pub struct DfxMetadata {
     /// # Pullable
     /// The required information so that the canister can be pulled using `dfx deps pull`.