Merge pull request #2997 from itowlson/schema-for-manifest

Generate schema for v2 manifest

Author: itowlson

.github/workflows/release.yml

@@ -34,6 +34,7 @@ jobs:
               extraArgs: "--features openssl/vendored",
               target: "",
               targetDir: "target/release",
+              generateManifestSchema: true,
             }
           - {
               os: "ubuntu-22.04",
@@ -132,6 +133,10 @@ jobs:
             --output-signature spin.sig \
             ${{ matrix.config.targetDir }}/spin${{ matrix.config.extension }}
 
+      - name: Generate manifest schema
+        if: matrix.config.generateManifestSchema
+        run: ${{ matrix.config.targetDir }}/spin${{ matrix.config.extension }} maintenance generate-manifest-schema -o manifest.schema.json
+
       - name: package release assets
         if: runner.os != 'Windows'
         shell: bash
@@ -167,6 +172,13 @@ jobs:
         with:
           name: spin-${{ env.RUNNER_OS }}-${{ matrix.config.arch }}
           path: _dist/spin-${{ env.RELEASE_VERSION }}-${{ env.RUNNER_OS }}-${{ matrix.config.arch }}.zip
+      
+      - name: Upload schema as GitHub artifact
+        if: matrix.config.generateManifestSchema
+        uses: actions/upload-artifact@v4
+        with:
+          name: manifest.schema.json
+          path: manifest.schema.json
 
   checksums:
     name: generate release checksums
@@ -206,13 +218,20 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: download release assets
+      - name: download binaries for release assets
         uses: actions/download-artifact@v4
         with:
           pattern: spin-*
           path: _dist
           merge-multiple: true
 
+      - name: download schema for release assets
+        uses: actions/download-artifact@v4
+        with:
+          pattern: manifest.schema.json
+          path: _dist
+          merge-multiple: true
+
       - name: check if pre-release
         shell: bash
         run: |

Cargo.lock

@@ -36,6 +36,7 @@ pretty_assertions = "1.3"
 regex = { workspace = true }
 reqwest = { workspace = true }
 rpassword = "7"
+schemars = { version = "0.8.21", features = ["indexmap2", "semver"] }
 semver = { workspace = true }
 serde = { version = "1", features = ["derive"] }
 serde_json = { workspace = true }

Cargo.toml

@@ -7,6 +7,7 @@ edition = { workspace = true }
 [dependencies]
 anyhow = { workspace = true }
 indexmap = { workspace = true, features = ["serde"] }
+schemars = { version = "0.8.21", features = ["indexmap2", "semver"] }
 semver = { workspace = true, features = ["serde"] }
 serde = { workspace = true }
 spin-serde = { path = "../serde" }

crates/manifest/Cargo.toml

@@ -60,6 +60,7 @@ pub fn v1_to_v2_app(manifest: v1::AppManifestV1) -> Result<v2::AppManifest, Erro
         };
         components.insert(
             component_id.clone(),
+            #[allow(deprecated)]
             v2::Component {
                 source: component.source,
                 description: component.description,

crates/manifest/src/compat.rs

@@ -1,11 +1,12 @@
 use std::fmt::Display;
 
+use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 use wasm_pkg_common::{package::PackageRef, registry::Registry};
 
 /// Variable definition
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct Variable {
     /// `required = true`
@@ -20,7 +21,7 @@ pub struct Variable {
 }
 
 /// Component source
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields, untagged)]
 pub enum ComponentSource {
     /// `"local.wasm"`
@@ -35,8 +36,10 @@ pub enum ComponentSource {
     /// `{ ... }`
     Registry {
         /// `registry = "example.com"`
+        #[schemars(with = "Option<String>")]
         registry: Option<Registry>,
         /// `package = "example:component"`
+        #[schemars(with = "String")]
         package: PackageRef,
         /// `version = "1.2.3"`
         version: String,
@@ -64,7 +67,7 @@ impl Display for ComponentSource {
 }
 
 /// WASI files mount
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields, untagged)]
 pub enum WasiFilesMount {
     /// `"images/*.png"`
@@ -79,7 +82,7 @@ pub enum WasiFilesMount {
 }
 
 /// Component build configuration
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ComponentBuildConfig {
     /// `command = "cargo build"`
@@ -104,7 +107,7 @@ impl ComponentBuildConfig {
 }
 
 /// Component build command or commands
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged)]
 pub enum Commands {
     /// `command = "cargo build"`

crates/manifest/src/schema/common.rs

@@ -0,0 +1,107 @@
+use crate::schema::v2::{ComponentSpec, Map, OneOrManyComponentSpecs};
+use schemars::JsonSchema;
+
+// The structs here allow dead code because they exist only
+// to represent JSON schemas, and are never instantiated.
+
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+pub struct TriggerSchema {
+    /// HTTP triggers
+    #[schemars(default)]
+    http: Vec<HttpTriggerSchema>,
+    /// Redis triggers
+    #[schemars(default)]
+    redis: Vec<RedisTriggerSchema>,
+}
+
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct HttpTriggerSchema {
+    /// `id = "trigger-id"`
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub id: String,
+    /// `component = ...`
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub component: Option<ComponentSpec>,
+    /// `components = { ... }`
+    #[serde(default, skip_serializing_if = "Map::is_empty")]
+    pub components: Map<String, OneOrManyComponentSpecs>,
+    /// `route = "/user/:name/..."`
+    route: HttpRouteSchema,
+    /// `executor = { type = "wagi" }
+    #[schemars(default, schema_with = "toml_table")]
+    executor: Option<toml::Table>,
+}
+
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[schemars(untagged)]
+pub enum HttpRouteSchema {
+    /// `route = "/user/:name/..."`
+    Route(String),
+    /// `route = { private = true }`
+    Private(HttpPrivateEndpoint),
+}
+
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct HttpPrivateEndpoint {
+    /// Whether the private endpoint is private. This must be true.
+    pub private: bool,
+}
+
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RedisTriggerSchema {
+    /// `id = "trigger-id"`
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub id: String,
+    /// `component = ...`
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub component: Option<ComponentSpec>,
+    /// `components = { ... }`
+    #[serde(default, skip_serializing_if = "Map::is_empty")]
+    pub components: Map<String, OneOrManyComponentSpecs>,
+    /// `channel = "my-messages"`
+    channel: String,
+    /// `address = "redis://redis.example.com:6379"`
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    address: Option<String>,
+}
+
+pub fn toml_table(_gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+    schemars::schema::Schema::Object(schemars::schema::SchemaObject {
+        instance_type: Some(schemars::schema::SingleOrVec::Single(Box::new(
+            schemars::schema::InstanceType::Object,
+        ))),
+        ..Default::default()
+    })
+}
+
+pub fn map_of_toml_tables(_gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+    schemars::schema::Schema::Object(schemars::schema::SchemaObject {
+        instance_type: Some(schemars::schema::SingleOrVec::Single(Box::new(
+            schemars::schema::InstanceType::Object,
+        ))),
+        ..Default::default()
+    })
+}
+
+pub fn one_or_many<T: schemars::JsonSchema>(
+    gen: &mut schemars::gen::SchemaGenerator,
+) -> schemars::schema::Schema {
+    schemars::schema::Schema::Object(schemars::schema::SchemaObject {
+        subschemas: Some(Box::new(schemars::schema::SubschemaValidation {
+            one_of: Some(vec![
+                gen.subschema_for::<T>(),
+                gen.subschema_for::<Vec<T>>(),
+            ]),
+            ..Default::default()
+        })),
+        ..Default::default()
+    })
+}

crates/manifest/src/schema/json_schema.rs

@@ -10,6 +10,7 @@ pub mod v2;
 // Types common between manifest versions. Re-exported from versioned modules
 // to make them easier to split if necessary.
 pub(crate) mod common;
+mod json_schema;
 
 #[derive(Deserialize)]
 pub(crate) struct VersionProbe {