Cherry-pick: CLI HelpText and JSON schema alignment to release/2.0 (#3417, #3444, #3454, #3471) by souvikghosh04 · Pull Request #3505 · Azure/data-api-builder

souvikghosh04 · 2026-05-05T16:15:32Z

Cherry-picks CLI HelpText and schema description improvements from main to release/2.0:

45f18e2 lowercase CLI enum values in HelpText and error messages (Group 3) (lowercase CLI enum values in HelpText and error messages (Group 3) #3444)
d8e0aa4 fix: align CLI HelpText defaults and descriptions with JSON schema (Group 2) (fix: align CLI HelpText defaults and descriptions with JSON schema (Group 2) #3417)
93edc20 Missing/Invalid Default Value (Group 4) (Missing/Invalid Default Value (Group 4) #3454)
acd6bf7 fix: improve schema descriptions (Group 5) (fix: improve schema descriptions (Group 5) #3471)

Note: This PR should be merged after #3504 (CLI structure fixes) as it depends on the new options introduced there.

…3444) ## Summary - Closes on #3445 Fixes 4 issues where CLI `--help` text and error messages showed PascalCase or UPPERCASE enum values instead of the lowercase values required by the JSON schema. The JSON serialization layer already produces lowercase (via `EnumMemberJsonEnumConverterFactory`), so these fixes align the CLI display layer to match. ## Issues Addressed | Issue | Option | CLI Showed | Schema Requires | Fix | |-------|--------|-----------|-----------------|-----| | #3361 | `--host-mode` (init) | `Development or Production` | `development or production` | HelpText lowercased | | #3362 | `--rest.methods` (add/update) | `[GET, POST, PUT, PATCH, DELETE]` | `[get, post, put, patch, delete]` | HelpText lowercased | | #3363 | `--graphql.operation` (add/update) | `[Query, Mutation]` | `[query, mutation]` | HelpText lowercased | | #3364 | `--graphql.operation` (add/update) | Same as #3363 | Same as #3363 | Same fix | ## Files Changed | File | Changes | |------|---------| | `src/Cli/Commands/InitOptions.cs` | `host-mode` HelpText: lowercase enum values | | `src/Cli/Commands/EntityOptions.cs` | `rest.methods` and `graphql.operation` HelpText: lowercase enum values | | `src/Cli/Utils.cs` | REST method and GraphQL operation error messages: lowercase enum names | ## Testing - [x] Unit tests Co-authored-by: Aniruddh Munde <anmunde@microsoft.com>

…roup 2) (#3417) - Closes on #3418 Fixes 14 issues where CLI option `--help` text showed incorrect default values, wrong descriptions, or enum mismatches compared to the JSON schema (`dab.draft.schema.json`) and C# runtime defaults. | # | Property | Before | After | Resolution | |---|----------|--------|-------|------------| | #3347 | `runtime.mcp.dml-tools.read-records` | CLI: true, Schema: false | Both: true | Schema changed false?true to match C# runtime | | #3348 | `runtime.mcp.dml-tools.create-record` | CLI: true, Schema: false | Both: true | Schema changed false?true to match C# runtime | | #3349 | `runtime.mcp.dml-tools.describe-entities` | CLI: true, Schema: false | Both: true | Schema changed false?true to match C# runtime | | #3350 | `runtime.graphql.multiple-mutations.create.enabled` | CLI: true, Schema: false | CLI: false | HelpText corrected to match schema | | #3351 | `runtime.host.mode` | CLI: Development, Schema: production | CLI: production | HelpText corrected to match schema | | #3352 | `data-source.options.set-session-context` | CLI: "(default)" text | No default | Removed misleading text | | #3353 | `runtime.rest.request-body-strict` | init: false, Schema: true | init: false | HelpText corrected to match schema | | #3354 | `runtime.mcp.dml-tools.aggregate-records` | Schema: .enabled=true, top-level=false | Both: true | Schema changed false?true to match C# runtime | | # | Property | Fix | |---|----------|-----| | #3355 | `--otel-service-name` | Changed description from "Headers for Open Telemetry" to "Service name for Open Telemetry" | | #3356 | `dab add-telemetry` options | Removed duplicate `(Default: X)` from HelpText where `Default=` attribute already displays the value | | #3357 | `runtime.graphql.depth-limit` | Changed description from "infinity"/"-1" to "Default: null (no limit)" | | # | Property | Fix | |---|----------|-----| | #3359 | `--database-type` (configure) | Already fixed in PR #3409 | | #3360 | `--database-type` (configure) | Changed to lowercase enum values | - #3378 (`rest.request-body-strict`) ? same fix as #3353 - #3379 (`host.mode`) ? same fix as #3351 - #3380 (`set-session-context`) ? same fix as #3352 - #3381 (`multiple-mutations.create.enabled`) ? same fix as #3350 - #3382 (DML tool defaults) ? same fix as #3347-#3349; schema aligned to `true` to match C# runtime | File | Changes | |------|---------| | `src/Cli/Commands/ConfigureOptions.cs` | 5 HelpText corrections (host.mode, multiple-mutations, set-session-context, depth-limit, database-type) | | `src/Cli/Commands/InitOptions.cs` | 2 HelpText corrections (request-body-strict, database-type) | | `src/Cli/Commands/AddTelemetryOptions.cs` | 4 HelpText/description corrections | | `schemas/dab.draft.schema.json` | DML tool defaults changed false?true (8 locations) to match C# runtime (`DmlToolsConfig.DEFAULT_ENABLED = true`) | - ConfigureOptionsTests: 78 passed, 0 failed - EndToEndTests: 138 passed, 0 failed, 3 skipped - Build: 0 warnings, 0 errors

## Why make this change? Parent issue #3466 Closes #3366 — `runtime.rest.enabled` has no `default` in the JSON schema Closes #3367 — `runtime.graphql.enabled` has no `default` in the JSON schema These schema properties were missing an explicit `default` value. 5 of 7 Group 4 issues (#3378–#3382) were already fixed in PR #3417 as Group 2 overlaps. ## What is this change? Adds `"default": true` to the `enabled` property under both `runtime.rest` and `runtime.graphql` in `schemas/dab.draft.schema.json`. This matches the C# runtime behavior where both REST and GraphQL are enabled by default. ## How was this tested? Schema-only metadata change — no runtime behavior affected. Validated that the schema still passes JSON Schema draft-07 validation. ## Sample Request(s) NA

## Why make this change? Closes #3470 Fixes #3365, #3368, #3369, #3370, #3371 Schema descriptions were missing, placeholder, or misleading — affecting VS Code IntelliSense and tooling that reads JSON Schema metadata. ## What is this change? Updates \schemas/dab.draft.schema.json\ descriptions: | Issue | Property | Fix | |-------|----------|-----| | #3365 | \data-source.health.enabled\ | Updated description | | #3368 | \permissions[].role\ | Added missing description (3 locations) | | #3369 | \permissions[].actions\ | Added missing description (3 locations) | | #3370 | \data-source.options\ | Clarified vague description (2 locations) | | #3371 | \ untime.graphql.depth-limit\ | Documented null (no limit) and -1 (CLI remove limit) semantics | ## How was this tested? Schema-only metadata change — no runtime behavior affected. JSON validated. --------- Co-authored-by: Copilot <copilot@github.com>

Copilot

Pull request overview

This PR cherry-picks a set of CLI --help text corrections and JSON schema metadata updates from main into release/2.0, with the goal of aligning CLI-displayed defaults/allowed values/descriptions with the runtime config JSON schema.

Changes:

Normalize CLI help/error-message display of enum values to match schema-required lowercase values (e.g., REST methods, GraphQL operations, host-mode).
Update dab configure HelpText defaults/descriptions and add several new CLI options intended to match newer schema fields.
Improve schemas/dab.draft.schema.json defaults and descriptions (including REST/GraphQL enabled defaults, depth-limit description, MCP DML tool defaults, and permissions descriptions).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`src/Cli/Utils.cs`	Lowercases supported REST method and GraphQL operation names in CLI error messages.
`src/Cli/Commands/InitOptions.cs`	Updates init HelpText to display lowercase host-mode values.
`src/Cli/Commands/EntityOptions.cs`	Updates stored-procedure-related HelpText to display lowercase REST/GraphQL enum values.
`src/Cli/Commands/ConfigureOptions.cs`	Updates/extends configure HelpText and introduces new configure options intended to align with schema/runtime.
`src/Cli/Commands/AddTelemetryOptions.cs`	Cleans up telemetry option HelpText to avoid duplicated default text and improve descriptions.
`schemas/dab.draft.schema.json`	Adjusts schema enums/defaults/descriptions to improve tooling IntelliSense and align with runtime behavior.

@@ -24,15 +24,15 @@
            "postgresql",
            "mysql",
            "cosmosdb_nosql",


              "$ref": "#/$defs/boolean-or-string",
              "description": "Does not allow extraneous fields in request body when set to true.",
-              "default": true
+              "default": false


+        public string? DataSourceUserDelegatedAuthProvider { get; }
+
+        [Option("data-source.health.enabled", Required = false, HelpText = "Enable health check for this data source. Default: true (boolean).")]
+        public bool? DataSourceHealthEnabled { get; }
+
+        [Option("data-source.health.threshold-ms", Required = false, HelpText = "Health check response time threshold in milliseconds. Default: 1000. Range: 1-2147483647.")]
+        public int? DataSourceHealthThresholdMs { get; }
+
+        [Option("data-source-files", Required = false, Separator = ',', HelpText = "Comma-separated list of additional runtime config files for multi-database scenarios.")]
+        public IEnumerable<string>? DataSourceFiles { get; }


+        public bool? RuntimeHealthEnabled { get; }
+
+        [Option("runtime.health.cache-ttl-seconds", Required = false, HelpText = "Time to live in seconds for cached health check results. Default: 5.")]
+        public int? RuntimeHealthCacheTtlSeconds { get; }
+
+        [Option("runtime.health.max-query-parallelism", Required = false, HelpText = "Maximum number of parallel health check queries. Default: 4. Range: 1-8.")]
+        public int? RuntimeHealthMaxQueryParallelism { get; }
+
+        [Option("runtime.health.roles", Required = false, Separator = ',', HelpText = "Comma-separated list of roles allowed to access health check details.")]
+        public IEnumerable<string>? RuntimeHealthRoles { get; }


+        [Option("data-source-files", Required = false, Separator = ',', HelpText = "Comma-separated list of additional runtime config files for multi-database scenarios.")]
+        public IEnumerable<string>? DataSourceFiles { get; }
+
+        [Option("runtime.graphql.depth-limit", Required = false, HelpText = "Max allowed depth of a nested query. Allowed values: 1-2147483647, or -1 to remove a previously set limit. Default: -1.")]


        public string? RuntimeRestPath { get; }

-        [Option("runtime.rest.request-body-strict", Required = false, HelpText = "Prohibit extraneous REST request body fields. Default: true (boolean).")]
+        [Option("runtime.rest.request-body-strict", Required = false, HelpText = "Prohibit extraneous REST request body fields. Default: false (boolean).")]


        }

-        [Option("data-source.database-type", Required = false, HelpText = "Database type. Allowed values: MSSQL, PostgreSQL, CosmosDB_NoSQL, MySQL.")]
+        [Option("data-source.database-type", Required = false, HelpText = "Database type. Allowed values: mssql, postgresql, cosmosdb_nosql, mysql, dwsql.")]


souvikghosh04 and others added 4 commits May 5, 2026 21:40

souvikghosh04 marked this pull request as ready for review May 5, 2026 16:17

Copilot AI review requested due to automatic review settings May 5, 2026 16:17

souvikghosh04 requested review from Alekhya-Polavarapu, Aniruddh25, JerryNixon, RubenCerna2079, aaronburtle, anushakolan, rusamant, sourabh1007, stuartpa and vadeveka as code owners May 5, 2026 16:17

Copilot started reviewing on behalf of souvikghosh04 May 5, 2026 16:18 View session

souvikghosh04 assigned Aniruddh25 and aaronburtle May 5, 2026

souvikghosh04 added 🍒Cherrypick Cherry-picking another commit/PR 2.0 labels May 5, 2026

souvikghosh04 added this to Data API builder May 5, 2026

github-project-automation Bot moved this to Todo in Data API builder May 5, 2026

souvikghosh04 added this to the May 2026 milestone May 5, 2026

souvikghosh04 moved this from Todo to Review In Progress in Data API builder May 5, 2026

Copilot AI reviewed May 5, 2026

View reviewed changes

Aniruddh25 approved these changes May 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cherry-pick: CLI HelpText and JSON schema alignment to release/2.0 (#3417, #3444, #3454, #3471)#3505

Cherry-pick: CLI HelpText and JSON schema alignment to release/2.0 (#3417, #3444, #3454, #3471)#3505
souvikghosh04 wants to merge 4 commits intorelease/2.0from
cherry-pick/release-2.0/cli-helptext-schema-alignment

souvikghosh04 commented May 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

souvikghosh04 commented May 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants