diff --git a/crates-cli/yaak-cli/src/cli.rs b/crates-cli/yaak-cli/src/cli.rs
index aac78599..bc5f3014 100644
--- a/crates-cli/yaak-cli/src/cli.rs
+++ b/crates-cli/yaak-cli/src/cli.rs
@@ -154,6 +154,10 @@ pub enum RequestCommands {
     Schema {
         #[arg(value_enum)]
         request_type: RequestSchemaType,
+
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
     },
 
     /// Create a new HTTP request
diff --git a/crates-cli/yaak-cli/src/commands/request.rs b/crates-cli/yaak-cli/src/commands/request.rs
index cae31811..a2b61c8f 100644
--- a/crates-cli/yaak-cli/src/commands/request.rs
+++ b/crates-cli/yaak-cli/src/commands/request.rs
@@ -35,8 +35,8 @@ pub async fn run(
                 }
             };
         }
-        RequestCommands::Schema { request_type } => {
-            return match schema(ctx, request_type).await {
+        RequestCommands::Schema { request_type, pretty } => {
+            return match schema(ctx, request_type, pretty).await {
                 Ok(()) => 0,
                 Err(error) => {
                     eprintln!("Error: {error}");
@@ -75,7 +75,7 @@ fn list(ctx: &CliContext, workspace_id: &str) -> CommandResult {
     Ok(())
 }
 
-async fn schema(ctx: &CliContext, request_type: RequestSchemaType) -> CommandResult {
+async fn schema(ctx: &CliContext, request_type: RequestSchemaType, pretty: bool) -> CommandResult {
     let mut schema = match request_type {
         RequestSchemaType::Http => serde_json::to_value(schema_for!(HttpRequest))
             .map_err(|e| format!("Failed to serialize HTTP request schema: {e}"))?,
@@ -91,7 +91,11 @@ async fn schema(ctx: &CliContext, request_type: RequestSchemaType) -> CommandRes
         eprintln!("Warning: Failed to enrich authentication schema from plugins: {error}");
     }
 
-    let output = serde_json::to_string_pretty(&schema)
+    let output = if pretty {
+        serde_json::to_string_pretty(&schema)
+    } else {
+        serde_json::to_string(&schema)
+    }
         .map_err(|e| format!("Failed to format schema JSON: {e}"))?;
     println!("{output}");
     Ok(())
diff --git a/crates-cli/yaak-cli/tests/request_commands.rs b/crates-cli/yaak-cli/tests/request_commands.rs
index 41ce02ac..1af18f71 100644
--- a/crates-cli/yaak-cli/tests/request_commands.rs
+++ b/crates-cli/yaak-cli/tests/request_commands.rs
@@ -189,12 +189,25 @@ fn request_schema_http_outputs_json_schema() {
         .args(["request", "schema", "http"])
         .assert()
         .success()
-        .stdout(contains("\"type\": \"object\""))
-        .stdout(contains("\"authentication\""))
+        .stdout(contains("\"type\":\"object\""))
+        .stdout(contains("\"authentication\":"))
         .stdout(contains("/foo/:id/comments/:commentId"))
         .stdout(contains("put concrete values in `urlParameters`"));
 }
 
+#[test]
+fn request_schema_http_pretty_prints_with_flag() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+
+    cli_cmd(data_dir)
+        .args(["request", "schema", "http", "--pretty"])
+        .assert()
+        .success()
+        .stdout(contains("\"type\": \"object\""))
+        .stdout(contains("\"authentication\""));
+}
+
 #[test]
 fn request_send_grpc_returns_explicit_nyi_error() {
     let temp_dir = TempDir::new().expect("Failed to create temp dir");
diff --git a/crates/yaak-models/src/models.rs b/crates/yaak-models/src/models.rs
index 7fef4dcd..7de47a90 100644
--- a/crates/yaak-models/src/models.rs
+++ b/crates/yaak-models/src/models.rs
@@ -611,6 +611,8 @@ pub struct Environment {
     pub base: bool,
     pub parent_model: String,
     pub parent_id: Option<String>,
+    /// Variables defined in this environment scope.
+    /// Child environments override parent variables by name.
     pub variables: Vec<EnvironmentVariable>,
     pub color: Option<String>,
     pub sort_priority: f64,
@@ -845,6 +847,8 @@ pub struct HttpUrlParameter {
     #[serde(default = "default_true")]
     #[ts(optional, as = "Option<bool>")]
     pub enabled: bool,
+    /// Colon-prefixed parameters are treated as path parameters if they match, like `/users/:id`
+    /// Other entries are appended as query parameters
     pub name: String,
     pub value: String,
     #[ts(optional, as = "Option<String>")]
@@ -877,6 +881,7 @@ pub struct HttpRequest {
     pub name: String,
     pub sort_priority: f64,
     pub url: String,
+    /// URL parameters used for both path placeholders (`:id`) and query string entries.
     pub url_parameters: Vec<HttpUrlParameter>,
 }
 
@@ -1118,6 +1123,7 @@ pub struct WebsocketRequest {
     pub name: String,
     pub sort_priority: f64,
     pub url: String,
+    /// URL parameters used for both path placeholders (`:id`) and query string entries.
     pub url_parameters: Vec<HttpUrlParameter>,
 }
 
@@ -1728,6 +1734,7 @@ pub struct GrpcRequest {
     pub name: String,
     pub service: Option<String>,
     pub sort_priority: f64,
+    /// Server URL (http for plaintext or https for secure)
     pub url: String,
 }