feat(wfe-server): gRPC reflection, auto-generated schema endpoints, Dockerfile

- tonic-reflection for gRPC service discovery
  - /schema/workflow.json (JSON Schema from schemars derives)
  - /schema/workflow.yaml (same schema in YAML)
  - /schema/workflow.proto (raw proto file)
  - Multi-stage alpine Dockerfile with all executor features
  - Comprehensive configuration reference (wfe-server/README.md)
  - Release script (scripts/release.sh)
  - Bumped to 1.8.1

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.1] - 2026-04-06
+
+### Added
+
+- **wfe-server**: gRPC reflection support via `tonic-reflection`
+- **wfe-server**: Schema endpoints: `/schema/workflow.json` (JSON Schema), `/schema/workflow.yaml` (YAML Schema), `/schema/workflow.proto` (raw proto)
+- **wfe-yaml**: Auto-generated JSON Schema from `schemars` derives on all YAML types
+- **wfe-server**: Dockerfile for multi-stage alpine build with all executor features
+- **wfe-server**: Comprehensive configuration reference (README.md)
+
+### Fixed
+
+- **wfe-yaml**: Added missing `license`, `repository`, `homepage` fields to Cargo.toml
+- **wfe-buildkit-protos**: Removed vendored Go repos (166MB -> 356K), kept only .proto files
+- **wfe-containerd-protos**: Removed vendored Go repos (53MB -> 216K), kept only .proto files
+- Filesystem loop warnings from circular symlinks in vendored Go modules eliminated
+- Pinned `icu_calendar <2.2` to work around `temporal_rs`/`deno_core` incompatibility
+
 ## [1.8.0] - 2026-04-06
 
 ### Added

Cargo.toml

@@ -3,7 +3,7 @@ members = ["wfe-core", "wfe-sqlite", "wfe-postgres", "wfe-opensearch", "wfe-valk
 resolver = "2"
 
 [workspace.package]
-version = "1.8.0"
+version = "1.8.1"
 edition = "2024"
 license = "MIT"
 repository = "https://src.sunbeam.pt/studio/wfe"
@@ -38,16 +38,16 @@ redis = { version = "0.27", features = ["tokio-comp", "connection-manager"] }
 opensearch = "2"
 
 # Internal crates
-wfe-core = { version = "1.8.0", path = "wfe-core", registry = "sunbeam" }
+wfe-core = { version = "1.8.1", path = "wfe-core", registry = "sunbeam" }
-wfe-sqlite = { version = "1.8.0", path = "wfe-sqlite", registry = "sunbeam" }
+wfe-sqlite = { version = "1.8.1", path = "wfe-sqlite", registry = "sunbeam" }
-wfe-postgres = { version = "1.8.0", path = "wfe-postgres", registry = "sunbeam" }
+wfe-postgres = { version = "1.8.1", path = "wfe-postgres", registry = "sunbeam" }
-wfe-opensearch = { version = "1.8.0", path = "wfe-opensearch", registry = "sunbeam" }
+wfe-opensearch = { version = "1.8.1", path = "wfe-opensearch", registry = "sunbeam" }
-wfe-valkey = { version = "1.8.0", path = "wfe-valkey", registry = "sunbeam" }
+wfe-valkey = { version = "1.8.1", path = "wfe-valkey", registry = "sunbeam" }
-wfe-yaml = { version = "1.8.0", path = "wfe-yaml", registry = "sunbeam" }
+wfe-yaml = { version = "1.8.1", path = "wfe-yaml", registry = "sunbeam" }
-wfe-buildkit = { version = "1.8.0", path = "wfe-buildkit", registry = "sunbeam" }
+wfe-buildkit = { version = "1.8.1", path = "wfe-buildkit", registry = "sunbeam" }
-wfe-containerd = { version = "1.8.0", path = "wfe-containerd", registry = "sunbeam" }
+wfe-containerd = { version = "1.8.1", path = "wfe-containerd", registry = "sunbeam" }
-wfe-rustlang = { version = "1.8.0", path = "wfe-rustlang", registry = "sunbeam" }
+wfe-rustlang = { version = "1.8.1", path = "wfe-rustlang", registry = "sunbeam" }
-wfe-kubernetes = { version = "1.8.0", path = "wfe-kubernetes", registry = "sunbeam" }
+wfe-kubernetes = { version = "1.8.1", path = "wfe-kubernetes", registry = "sunbeam" }
 
 # YAML
 serde_yaml = "0.9"

scripts/release.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="${1:?Usage: scripts/release.sh <version> [message]}"
+MESSAGE="${2:-v${VERSION}}"
+
+echo "=== Releasing v${VERSION} ==="
+
+# Tag
+git tag -a "v${VERSION}" -m "${MESSAGE}"
+
+# Publish leaf crates
+for crate in wfe-core wfe-containerd-protos wfe-buildkit-protos wfe-server-protos; do
+    echo "--- Publishing ${crate} ---"
+    cargo publish -p "${crate}" --registry sunbeam
+done
+
+# Middle layer
+for crate in wfe-sqlite wfe-postgres wfe-opensearch wfe-valkey wfe-buildkit wfe-containerd wfe-rustlang; do
+    echo "--- Publishing ${crate} ---"
+    cargo publish -p "${crate}" --registry sunbeam
+done
+
+# Top layer (needs index to catch up)
+sleep 10
+for crate in wfe wfe-yaml; do
+    echo "--- Publishing ${crate} ---"
+    cargo publish -p "${crate}" --registry sunbeam
+done
+
+# Final layer
+sleep 10
+for crate in wfe-server wfe-deno wfe-kubernetes; do
+    echo "--- Publishing ${crate} ---"
+    cargo publish -p "${crate}" --registry sunbeam
+done
+
+# Push git
+git push origin mainline
+git push origin "v${VERSION}"
+
+# Create Gitea release from changelog
+release_body=$(awk -v ver="${VERSION}" '/^## \[/{if(found)exit;if(index($0,"["ver"]"))found=1;next}found{print}' CHANGELOG.md)
+tea release create --tag "v${VERSION}" --title "v${VERSION}" --note "${release_body}" || echo "(release already exists)"
+
+# Build + push Docker image
+echo "--- Building Docker image ---"
+docker buildx build --builder sunbeam-remote --platform linux/amd64 \
+    -t "src.sunbeam.pt/studio/wfe:${VERSION}" \
+    -t "src.sunbeam.pt/studio/wfe:latest" \
+    --push .
+
+echo "=== v${VERSION} released ==="

wfe-buildkit/Cargo.toml

@@ -16,7 +16,7 @@ async-trait = { workspace = true }
 tracing = { workspace = true }
 thiserror = { workspace = true }
 regex = { workspace = true }
-wfe-buildkit-protos = { version = "1.8.0", path = "../wfe-buildkit-protos", registry = "sunbeam" }
+wfe-buildkit-protos = { version = "1.8.1", path = "../wfe-buildkit-protos", registry = "sunbeam" }
 tonic = "0.14"
 tower = { version = "0.4", features = ["util"] }
 hyper-util = { version = "0.1", features = ["tokio"] }

wfe-containerd/Cargo.toml

@@ -9,7 +9,7 @@ description = "containerd container runner executor for WFE"
 
 [dependencies]
 wfe-core = { workspace = true }
-wfe-containerd-protos = { version = "1.8.0", path = "../wfe-containerd-protos", registry = "sunbeam" }
+wfe-containerd-protos = { version = "1.8.1", path = "../wfe-containerd-protos", registry = "sunbeam" }
 tokio = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }

wfe-deno/Cargo.toml

@@ -9,7 +9,7 @@ description = "Deno bindings for the WFE workflow engine"
 
 [dependencies]
 wfe-core = { workspace = true, features = ["test-support"] }
-wfe = { version = "1.8.0", path = "../wfe", registry = "sunbeam" }
+wfe = { version = "1.8.1", path = "../wfe", registry = "sunbeam" }
 deno_core = { workspace = true }
 deno_error = { workspace = true }
 tokio = { workspace = true }

wfe-server-protos/build.rs

@@ -1,12 +1,18 @@
+use std::path::PathBuf;
+
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let proto_files = vec!["proto/wfe/v1/wfe.proto"];
 
+    let out_dir = PathBuf::from(std::env::var("OUT_DIR")?);
+    let descriptor_path = out_dir.join("wfe_descriptor.bin");
+
     let mut prost_config = prost_build::Config::new();
     prost_config.include_file("mod.rs");
 
     tonic_prost_build::configure()
         .build_server(true)
         .build_client(true)
+        .file_descriptor_set_path(&descriptor_path)
         .compile_with_config(
             prost_config,
             &proto_files,

wfe-server-protos/src/lib.rs

@@ -15,3 +15,6 @@ include!(concat!(env!("OUT_DIR"), "/mod.rs"));
 pub use prost;
 pub use prost_types;
 pub use tonic;
+
+/// Encoded file descriptor set for gRPC reflection.
+pub const FILE_DESCRIPTOR_SET: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/wfe_descriptor.bin"));

wfe-server/Cargo.toml

@@ -14,9 +14,9 @@ path = "src/main.rs"
 [dependencies]
 # Internal
 wfe-core = { workspace = true, features = ["test-support"] }
-wfe = { version = "1.8.0", path = "../wfe", registry = "sunbeam" }
+wfe = { version = "1.8.1", path = "../wfe", registry = "sunbeam" }
-wfe-yaml = { version = "1.8.0", path = "../wfe-yaml", registry = "sunbeam", features = ["rustlang", "buildkit", "containerd"] }
+wfe-yaml = { version = "1.8.1", path = "../wfe-yaml", registry = "sunbeam", features = ["rustlang", "buildkit", "containerd"] }
-wfe-server-protos = { version = "1.8.0", path = "../wfe-server-protos", registry = "sunbeam" }
+wfe-server-protos = { version = "1.8.1", path = "../wfe-server-protos", registry = "sunbeam" }
 wfe-sqlite = { workspace = true }
 wfe-postgres = { workspace = true }
 wfe-valkey = { workspace = true }
@@ -26,6 +26,7 @@ opensearch = { workspace = true }
 # gRPC
 tonic = "0.14"
 tonic-health = "0.14"
+tonic-reflection = "0.14"
 prost-types = "0.14"
 
 # HTTP (webhooks)

wfe-server/src/main.rs

@@ -172,6 +172,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .route("/webhooks/github", axum::routing::post(webhook::handle_github_webhook))
         .route("/webhooks/gitea", axum::routing::post(webhook::handle_gitea_webhook))
         .route("/healthz", axum::routing::get(webhook::health_check))
+        .route("/schema/workflow.proto", axum::routing::get(serve_proto_schema))
+        .route("/schema/workflow.json", axum::routing::get(serve_json_schema))
+        .route("/schema/workflow.yaml", axum::routing::get(serve_yaml_example))
         .layer(axum::extract::DefaultBodyLimit::max(2 * 1024 * 1024))
         .with_state(webhook_state);
 
@@ -180,8 +183,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let http_addr = config.http_addr;
     tracing::info!(%grpc_addr, %http_addr, "servers listening");
 
+    let reflection_service = tonic_reflection::server::Builder::configure()
+        .register_encoded_file_descriptor_set(wfe_server_protos::FILE_DESCRIPTOR_SET)
+        .build_v1()
+        .expect("failed to build reflection service");
+
     let grpc_server = Server::builder()
         .add_service(health_service)
+        .add_service(reflection_service)
         .add_service(WfeServer::with_interceptor(wfe_service, auth_interceptor))
         .serve(grpc_addr);
 
@@ -248,3 +257,25 @@ async fn load_yaml_definitions(host: &wfe::WorkflowHost, dir: &std::path::Path)
         }
     }
 }
+
+/// Serve the raw .proto schema file.
+async fn serve_proto_schema() -> impl axum::response::IntoResponse {
+    (
+        [(axum::http::header::CONTENT_TYPE, "text/plain; charset=utf-8")],
+        include_str!("../../wfe-server-protos/proto/wfe/v1/wfe.proto"),
+    )
+}
+
+/// Serve the auto-generated JSON Schema for workflow YAML definitions.
+async fn serve_json_schema() -> impl axum::response::IntoResponse {
+    let schema = wfe_yaml::schema::generate_json_schema();
+    axum::Json(schema)
+}
+
+/// Serve the auto-generated JSON Schema as YAML.
+async fn serve_yaml_example() -> impl axum::response::IntoResponse {
+    (
+        [(axum::http::header::CONTENT_TYPE, "text/yaml; charset=utf-8")],
+        wfe_yaml::schema::generate_yaml_schema(),
+    )
+}

wfe-yaml/Cargo.toml

@@ -27,6 +27,7 @@ thiserror = { workspace = true }
 tracing = { workspace = true }
 chrono = { workspace = true }
 regex = { workspace = true }
+schemars = { version = "1", features = ["derive"] }
 deno_core = { workspace = true, optional = true }
 deno_error = { workspace = true, optional = true }
 url = { workspace = true, optional = true }

wfe-yaml/src/schema.rs

@@ -1,13 +1,14 @@
 use std::collections::HashMap;
 
-use serde::Deserialize;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
 
 /// A condition in YAML that determines whether a step executes.
 ///
 /// Uses `#[serde(untagged)]` so serde tries each variant in order.
 /// A comparison has a `field:` key; a combinator has `all:/any:/none:/one_of:/not:`.
 /// Comparison is listed first because it is more specific (requires `field`).
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 #[serde(untagged)]
 pub enum YamlCondition {
     /// Leaf comparison (has a `field:` key).
@@ -17,7 +18,7 @@ pub enum YamlCondition {
 }
 
 /// A combinator condition containing sub-conditions.
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct YamlCombinator {
     #[serde(default)]
     pub all: Option<Vec<YamlCondition>>,
@@ -32,22 +33,29 @@ pub struct YamlCombinator {
 }
 
 /// A leaf comparison condition that compares a field value.
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct YamlComparison {
     pub field: String,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub equals: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub not_equals: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub gt: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub gte: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub lt: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub lte: Option<serde_yaml::Value>,
     #[serde(default)]
+    #[schemars(with = "Option<serde_json::Value>")]
     pub contains: Option<serde_yaml::Value>,
     #[serde(default)]
     pub is_null: Option<bool>,
@@ -56,7 +64,7 @@ pub struct YamlComparison {
 }
 
 /// Top-level YAML file structure supporting both single and multi-workflow files.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlWorkflowFile {
     /// Single workflow (backward compatible).
     pub workflow: Option<WorkflowSpec>,
@@ -66,19 +74,25 @@ pub struct YamlWorkflowFile {
 
 /// Legacy single-workflow top-level structure. Kept for backward compatibility
 /// with code that deserializes `YamlWorkflow` directly.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlWorkflow {
     pub workflow: WorkflowSpec,
 }
 
-#[derive(Debug, Deserialize)]
+/// A complete workflow definition.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct WorkflowSpec {
+    /// Unique workflow identifier.
     pub id: String,
+    /// Workflow version number.
     pub version: u32,
+    /// Optional human-readable description.
     #[serde(default)]
     pub description: Option<String>,
+    /// Default error handling behavior for all steps.
     #[serde(default)]
     pub error_behavior: Option<YamlErrorBehavior>,
+    /// The steps that make up this workflow.
     pub steps: Vec<YamlStep>,
     /// Typed input schema: { field_name: type_string }.
     /// Example: `"repo_url": "string"`, `"tags": "list<string>"`.
@@ -87,36 +101,45 @@ pub struct WorkflowSpec {
     /// Typed output schema: { field_name: type_string }.
     #[serde(default)]
     pub outputs: HashMap<String, String>,
-    /// Infrastructure services required by this workflow.
+    /// Infrastructure services required by this workflow (databases, caches, etc.).
     #[serde(default)]
     pub services: HashMap<String, YamlService>,
     /// Allow unknown top-level keys (e.g. `_templates`) for YAML anchors.
     #[serde(flatten)]
+    #[schemars(skip)]
     pub _extra: HashMap<String, serde_yaml::Value>,
 }
 
 /// A service definition in YAML format.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlService {
+    /// Container image to run (e.g., "postgres:15").
     pub image: String,
+    /// Ports to expose (container ports).
     #[serde(default)]
     pub ports: Vec<u16>,
+    /// Environment variables for the service container.
     #[serde(default)]
     pub env: HashMap<String, String>,
+    /// Readiness probe configuration.
     #[serde(default)]
     pub readiness: Option<YamlReadiness>,
+    /// Memory limit (e.g., "512Mi").
     #[serde(default)]
     pub memory: Option<String>,
+    /// CPU limit (e.g., "500m").
     #[serde(default)]
     pub cpu: Option<String>,
+    /// Override container entrypoint.
     #[serde(default)]
     pub command: Option<Vec<String>>,
+    /// Override container args.
     #[serde(default)]
     pub args: Option<Vec<String>>,
 }
 
 /// Readiness probe configuration in YAML format.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlReadiness {
     /// Execute a command to check readiness.
     #[serde(default)]
@@ -139,9 +162,11 @@ pub struct YamlReadiness {
 }
 
 /// HTTP GET readiness check.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlHttpGet {
+    /// Port to check.
     pub port: u16,
+    /// HTTP path (default: "/").
     #[serde(default = "default_health_path")]
     pub path: String,
 }
@@ -150,179 +175,261 @@ fn default_health_path() -> String {
     "/".into()
 }
 
-#[derive(Debug, Deserialize)]
+/// A single step in a workflow.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlStep {
+    /// Step identifier (must be unique within the workflow).
     pub name: String,
+    /// Executor type. One of: shell, deno, containerd, buildkit, kubernetes, k8s,
+    /// cargo-build, cargo-test, cargo-check, cargo-clippy, cargo-fmt, cargo-doc,
+    /// cargo-publish, cargo-audit, cargo-deny, cargo-nextest, cargo-llvm-cov,
+    /// cargo-doc-mdx, rust-install, rustup-toolchain, rustup-component,
+    /// rustup-target, workflow. Default: "shell".
     #[serde(rename = "type")]
     pub step_type: Option<String>,
+    /// Type-specific configuration.
     #[serde(default)]
     pub config: Option<StepConfig>,
+    /// Input data references.
     #[serde(default)]
     pub inputs: Vec<DataRef>,
+    /// Output data references.
     #[serde(default)]
     pub outputs: Vec<DataRef>,
+    /// Steps to run in parallel.
     #[serde(default)]
     pub parallel: Option<Vec<YamlStep>>,
+    /// Error handling override for this step.
     #[serde(default)]
     pub error_behavior: Option<YamlErrorBehavior>,
+    /// Hook step to run on success.
     #[serde(default)]
     pub on_success: Option<Box<YamlStep>>,
+    /// Compensation step to run on failure.
     #[serde(default)]
     pub on_failure: Option<Box<YamlStep>>,
+    /// Cleanup step that always runs.
     #[serde(default)]
     pub ensure: Option<Box<YamlStep>>,
-    /// Optional condition that must be true for this step to execute.
+    /// Condition that must be true for this step to execute.
     #[serde(default)]
     pub when: Option<YamlCondition>,
 }
 
-#[derive(Debug, Deserialize, Clone)]
+/// Step configuration (fields are type-specific).
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct StepConfig {
+    // --- Shell ---
+    /// Shell command to run (shorthand for shell steps).
     pub run: Option<String>,
+    /// Path to a script file (deno steps).
     pub file: Option<String>,
+    /// Inline script source (deno steps).
     pub script: Option<String>,
+    /// Shell binary to use (default: "sh").
     pub shell: Option<String>,
+    /// Environment variables.
     #[serde(default)]
     pub env: HashMap<String, String>,
+    /// Execution timeout (e.g., "5m", "30s").
     pub timeout: Option<String>,
+    /// Working directory.
     pub working_dir: Option<String>,
+
+    // --- Deno ---
+    /// Deno sandbox permissions.
     #[serde(default)]
     pub permissions: Option<DenoPermissionsYaml>,
+    /// ES modules to import (e.g., "npm:lodash@4").
     #[serde(default)]
     pub modules: Vec<String>,
-    // BuildKit fields
+
+    // --- BuildKit ---
+    /// Dockerfile path.
     pub dockerfile: Option<String>,
+    /// Build context path.
     pub context: Option<String>,
+    /// Multi-stage build target.
     pub target: Option<String>,
+    /// Image tags.
     #[serde(default)]
     pub tags: Vec<String>,
+    /// Build arguments.
     #[serde(default)]
     pub build_args: HashMap<String, String>,
+    /// Cache import sources.
     #[serde(default)]
     pub cache_from: Vec<String>,
+    /// Cache export destinations.
     #[serde(default)]
     pub cache_to: Vec<String>,
+    /// Push built image to registry.
     pub push: Option<bool>,
+    /// BuildKit daemon address.
     pub buildkit_addr: Option<String>,
+    /// TLS configuration.
     #[serde(default)]
     pub tls: Option<TlsConfigYaml>,
+    /// Registry authentication per registry hostname.
     #[serde(default)]
     pub registry_auth: Option<HashMap<String, RegistryAuthYaml>>,
-    // Containerd fields
+
+    // --- Containerd ---
+    /// Container image (required for containerd/kubernetes steps).
     pub image: Option<String>,
+    /// Container command override.
     #[serde(default)]
     pub command: Option<Vec<String>>,
+    /// Volume mounts.
     #[serde(default)]
     pub volumes: Vec<VolumeMountYaml>,
+    /// User:group (e.g., "1000:1000").
     pub user: Option<String>,
+    /// Network mode: none, host, bridge.
     pub network: Option<String>,
+    /// Memory limit (e.g., "512m").
     pub memory: Option<String>,
+    /// CPU limit (e.g., "1.0").
     pub cpu: Option<String>,
+    /// Image pull policy: always, if-not-present, never.
     pub pull: Option<String>,
+    /// Containerd daemon address.
     pub containerd_addr: Option<String>,
-    /// CLI binary name for containerd steps: "nerdctl" (default) or "docker".
+    /// CLI binary name: "nerdctl" (default) or "docker".
     pub cli: Option<String>,
-    // Kubernetes fields
+
-    /// Kubeconfig path for kubernetes steps.
+    // --- Kubernetes ---
+    /// Kubeconfig path.
     pub kubeconfig: Option<String>,
-    /// Namespace override for kubernetes steps.
+    /// Namespace override.
     pub namespace: Option<String>,
-    /// Image pull policy for kubernetes steps: Always, IfNotPresent, Never.
+    /// Image pull policy: Always, IfNotPresent, Never.
     pub pull_policy: Option<String>,
-    // Cargo fields
+
+    // --- Cargo ---
     /// Target package for cargo steps (`-p`).
     pub package: Option<String>,
-    /// Features to enable for cargo steps.
+    /// Features to enable.
     #[serde(default)]
     pub features: Vec<String>,
-    /// Enable all features for cargo steps.
+    /// Enable all features.
     #[serde(default)]
     pub all_features: Option<bool>,
-    /// Disable default features for cargo steps.
+    /// Disable default features.
     #[serde(default)]
     pub no_default_features: Option<bool>,
-    /// Build in release mode for cargo steps.
+    /// Build in release mode.
     #[serde(default)]
     pub release: Option<bool>,
-    /// Build profile for cargo steps (`--profile`).
+    /// Build profile (--profile).
     pub profile: Option<String>,
-    /// Rust toolchain override for cargo steps (e.g. "nightly").
+    /// Rust toolchain override (e.g., "nightly").
     pub toolchain: Option<String>,
-    /// Additional arguments for cargo/rustup steps.
+    /// Additional CLI arguments.
     #[serde(default)]
     pub extra_args: Vec<String>,
-    /// Output directory for generated files (e.g., MDX docs).
+    /// Output directory for generated files.
     pub output_dir: Option<String>,
-    // Rustup fields
+
-    /// Components to add for rustup steps (e.g. ["clippy", "rustfmt"]).
+    // --- Rustup ---
+    /// Components to add (e.g., ["clippy", "rustfmt"]).
     #[serde(default)]
     pub components: Vec<String>,
-    /// Compilation targets to add for rustup steps (e.g. ["wasm32-unknown-unknown"]).
+    /// Compilation targets to add.
     #[serde(default)]
     pub targets: Vec<String>,
     /// Default toolchain for rust-install steps.
     pub default_toolchain: Option<String>,
-    // Workflow (sub-workflow) fields
+
-    /// Child workflow ID (for `type: workflow` steps).
+    // --- Sub-workflow ---
+    /// Child workflow ID.
     #[serde(rename = "workflow")]
     pub child_workflow: Option<String>,
-    /// Child workflow version (for `type: workflow` steps).
+    /// Child workflow version.
     #[serde(rename = "workflow_version")]
     pub child_version: Option<u32>,
 }
 
-/// YAML-level permission configuration for Deno steps.
+/// Deno sandbox permission configuration.
-#[derive(Debug, Deserialize, Clone, Default)]
+#[derive(Debug, Deserialize, Serialize, Clone, Default, JsonSchema)]
 pub struct DenoPermissionsYaml {
+    /// Allowed network hosts.
     #[serde(default)]
     pub net: Vec<String>,
+    /// Allowed read paths.
     #[serde(default)]
     pub read: Vec<String>,
+    /// Allowed write paths.
     #[serde(default)]
     pub write: Vec<String>,
+    /// Allowed environment variable names.
     #[serde(default)]
     pub env: Vec<String>,
+    /// Allow subprocess execution.
     #[serde(default)]
     pub run: bool,
+    /// Allow dynamic imports.
     #[serde(default)]
     pub dynamic_import: bool,
 }
 
-#[derive(Debug, Deserialize)]
+/// Data reference for step inputs/outputs.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct DataRef {
     pub name: String,
     pub path: Option<String>,
     pub json_path: Option<String>,
 }
 
-/// YAML-level TLS configuration for BuildKit steps.
+/// TLS configuration for BuildKit connections.
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct TlsConfigYaml {
     pub ca: Option<String>,
     pub cert: Option<String>,
     pub key: Option<String>,
 }
 
-/// YAML-level registry auth configuration for BuildKit steps.
+/// Registry authentication credentials.
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct RegistryAuthYaml {
     pub username: String,
     pub password: String,
 }
 
-/// YAML-level volume mount configuration for containerd steps.
+/// Volume mount configuration for containerd steps.
-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, JsonSchema)]
 pub struct VolumeMountYaml {
+    /// Host path.
     pub source: String,
+    /// Container path.
     pub target: String,
+    /// Mount as read-only.
     #[serde(default)]
     pub readonly: bool,
 }
 
-#[derive(Debug, Deserialize)]
+/// Error handling behavior configuration.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct YamlErrorBehavior {
+    /// Behavior type: retry, suspend, terminate, compensate.
     #[serde(rename = "type")]
     pub behavior_type: String,
+    /// Retry interval (e.g., "60s").
     pub interval: Option<String>,
+    /// Maximum retry attempts.
     pub max_retries: Option<u32>,
 }
+
+/// Generate the JSON Schema for the WFE workflow YAML format.
+pub fn generate_json_schema() -> serde_json::Value {
+    let schema = schemars::generate::SchemaSettings::default()
+        .into_generator()
+        .into_root_schema_for::<YamlWorkflowFile>();
+    serde_json::to_value(schema).unwrap_or_default()
+}
+
+/// Generate the JSON Schema as YAML for human consumption.
+pub fn generate_yaml_schema() -> String {
+    let schema = generate_json_schema();
+    serde_yaml::to_string(&schema).unwrap_or_default()
+}