add schema output

Author: ss2165

Cargo.lock

@@ -91,6 +91,7 @@ pretty_assertions = "1.4.1"
 zstd = "0.13.2"
 relrc = "0.5.0"
 wyhash = "0.6.0"
+schemars = "1.0.4"
 
 # These public dependencies usually require breaking changes downstream, so we
 # try to be as permissive as possible.

Cargo.toml

@@ -28,6 +28,8 @@ thiserror.workspace = true
 tracing = "0.1.41"
 tracing-subscriber = { version = "0.3.20", features = ["fmt"] }
 tabled = "0.20.0"
+schemars = { workspace = true, features = ["derive"] }
+
 
 [lints]
 workspace = true

hugr-cli/Cargo.toml

@@ -1,6 +1,4 @@
 //! Describe the contents of HUGR packages.
-use std::io::Write;
-
 use crate::hugr_io::HugrInputArgs;
 use anyhow::Result;
 use clap::Parser;
@@ -10,6 +8,7 @@ use hugr::envelope::ReadError;
 use hugr::envelope::description::{ExtensionDesc, ModuleDesc, PackageDesc};
 use hugr::extension::Version;
 use hugr::package::Package;
+use std::io::Write;
 use tabled::Tabled;
 use tabled::derive::display;
 
@@ -31,10 +30,15 @@ pub struct DescribeArgs {
     /// Configure module description
     pub module_args: ModuleArgs,
 
-    #[arg(long, default_value = "false")]
+    #[arg(long, default_value = "false", help_heading = "JSON")]
     /// Output in json format
     pub json: bool,
 
+    #[arg(long, default_value = "false", help_heading = "JSON")]
+    /// Output JSON schema for the description format.
+    /// Can't be combined with --json.
+    pub json_schema: bool,
+
     /// Output file. Use '-' for stdout.
     #[clap(short, long, value_parser, default_value = "-")]
     pub output: Output,
@@ -71,6 +75,12 @@ impl ModuleArgs {
 impl DescribeArgs {
     /// Load and describe the HUGR package.
     pub fn run_describe(&mut self) -> Result<()> {
+        if self.json_schema {
+            let schema = schemars::schema_for!(PackageDescriptionJson);
+            let schema_json = serde_json::to_string_pretty(&schema)?;
+            writeln!(self.output, "{schema_json}")?;
+            return Ok(());
+        }
         let (mut desc, res) = match self.input_args.get_described_package() {
             Ok((desc, pkg)) => (desc, Ok(pkg)),
             Err(crate::CliError::ReadEnvelope(ReadError::Payload {
@@ -143,7 +153,7 @@ impl DescribeArgs {
 
     fn output_json(&mut self, package_desc: PackageDesc, res: &Result<Package>) -> Result<()> {
         let err_str = res.as_ref().err().map(|e| format!("{e:?}"));
-        let json_desc = JsonDescription {
+        let json_desc = PackageDescriptionJson {
             package_desc,
             error: err_str,
         };
@@ -173,8 +183,8 @@ impl DescribeArgs {
     }
 }
 
-#[derive(serde::Serialize)]
-struct JsonDescription {
+#[derive(serde::Serialize, schemars::JsonSchema)]
+struct PackageDescriptionJson {
     #[serde(flatten)]
     package_desc: PackageDesc,
     #[serde(skip_serializing_if = "Option::is_none")]

hugr-cli/src/describe.rs

@@ -274,3 +274,168 @@ fn test_describe_invalid_package_json(invalid_package: Vec<u8>, mut describe_cmd
         .stdout(contains("\"error\": \"Error reading a HUGR model payload")) // error included in JSON
         .stderr(contains("Error reading a HUGR model payload"));
 }
+
+#[rstest]
+fn test_schema(mut describe_cmd: Command) {
+    describe_cmd.arg("--json-schema");
+    let output = describe_cmd.assert().success().get_output().stdout.clone();
+    let schema: Value = serde_json::from_slice(&output).unwrap();
+    let expected = json!(
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "PackageDescriptionJson",
+      "description": "High-level description of a HUGR package.",
+      "type": "object",
+      "properties": {
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "header": {
+          "description": "Envelope header information.",
+          "type": "string"
+        },
+        "modules": {
+          "description": "Description of the modules in the package.",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/ModuleDesc"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "packaged_extensions": {
+          "description": "Description of the extensions in the package.",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/ExtensionDesc"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      },
+      "required": [
+        "header",
+        "modules"
+      ],
+      "$defs": {
+        "Entrypoint": {
+          "description": "Description of the entrypoint of a module.",
+          "type": "object",
+          "properties": {
+            "node": {
+              "description": "Node id of the entrypoint.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0
+            },
+            "optype": {
+              "description": "Operation type of the entrypoint node.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "node",
+            "optype"
+          ]
+        },
+        "ExtensionDesc": {
+          "description": "High level description of an extension.",
+          "type": "object",
+          "properties": {
+            "name": {
+              "description": "Name of the extension.",
+              "type": "string"
+            },
+            "version": {
+              "description": "Version of the extension.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "version"
+          ]
+        },
+        "ModuleDesc": {
+          "description": "High-level description of a module in a HUGR package.",
+          "type": "object",
+          "properties": {
+            "entrypoint": {
+              "description": "The entrypoint node and the corresponding operation type.",
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/Entrypoint"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "generator": {
+              "description": "Generator specified in the module metadata.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "num_nodes": {
+              "description": "Number of nodes in the module.",
+              "type": [
+                "integer",
+                "null"
+              ],
+              "format": "uint",
+              "minimum": 0
+            },
+            "public_symbols": {
+              "description": "Public symbols defined in the module.",
+              "type": [
+                "array",
+                "null"
+              ],
+              "items": {
+                "type": "string"
+              }
+            },
+            "used_extensions_generator": {
+              "description": "Generator specified used extensions in the module metadata.",
+              "type": [
+                "array",
+                "null"
+              ],
+              "items": {
+                "$ref": "#/$defs/ExtensionDesc"
+              }
+            },
+            "used_extensions_resolved": {
+              "description": "Extensions used in the module computed while resolving, expected to be a subset of `used_extensions_generator`.",
+              "type": [
+                "array",
+                "null"
+              ],
+              "items": {
+                "$ref": "#/$defs/ExtensionDesc"
+              }
+            }
+          }
+        }
+      }
+    }
+
+    );
+
+    assert_eq!(schema, expected);
+}

hugr-cli/tests/describe.rs

@@ -65,6 +65,7 @@ base64.workspace = true
 relrc = { workspace = true, features = ["petgraph", "serde"] }
 smallvec = { workspace = true }
 tracing = "0.1.41"
+schemars = { workspace = true, features = ["derive"] }
 
 [dev-dependencies]
 rstest = { workspace = true }