Commit 4c5038f
authored
[MCP] Added parameter description. (#2904)
## Why make this change?
- Expands stored procedure parameter definitions in the configuration
file to support richer metadata, using parameter's attributes like,
`name`, `description`, `required`, and `default` values.
- Enables MCP and other tooling to leverage parameter metadata for
improved documentation, validation, and user experience.
- Supports backward compatibility by allowing both the legacy dictionary
format and the new array-of-objects format for parameters.
## What is this change?
- Changes the `parameters` property in entity config from a dictionary
mapping parameter names to values, to an array of parameter objects with
explicit fields (`name`, `required`, `default`, `description`).
- Updates the JSON schema to support the new structure and maintain
support for the old syntax.
- Refactors the internal model to handle both formats and expose richer
metadata.
- Enhances CLI commands (`dab add` and `dab update`) to accept and
manage parameter metadata fields: `name`, `required`, `default`, and
`description`.
- Adds support for the expanded parameter object in CLI validation,
including deprecation notes for the legacy format.
- Includes parameter descriptions in DAB's OpenAPI and GraphQL schema
outputs for improved API documentation.
- This change also introduces smarter handling of optional parameters
for stored procedures. If a parameter is not required and neither a user
value nor a config default is provided, DAB will skip sending that
parameter, allowing the database’s internal default to apply. This
avoids duplication and drift between config and database defaults. The
old behavior is fully supported for backward compatibility.
## How was this tested?
- [x] Manual Testing:
- Used CLI commands to add, validate and update parameters with
metadata.
- Verified config parsing, CLI commands, and schema generation for both
legacy and expanded parameter formats.
- Confirmed correct behavior in OpenAPI and GraphQL outputs.
## Sample Request(s)
**Before (legacy dictionary format):**
```json
{
"entities": {
"User": {
"source": {
"parameters": {
"param1": "default-value"
}
}
}
}
}
```
**After (expanded array format):**
```json
{
"entities": {
"User": {
"source": {
"parameters": [
{
"name": "Id",
"required": true,
"default": "default-value",
"description": "The unique identifier for the user."
}
]
}
}
}
}
```
**Command Line Examples:**
**Before (legacy dictionary format):**
```
dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll add MyProc --source "dbo.MyProc" --source.type stored-procedure --source.params "PageSize:50,SortOrder:ASC" --permissions "anonymous:execute" "authenticated:execute" --config C:\DAB\data-api-builder\src\Service\dab-config.json
```
```
"MyProc": {
"source": {
"object": "dbo.MyProc",
"type": "stored-procedure",
"parameters": [
{
"name": "PageSize",
"required": false,
"default": "50"
},
{
"name": "SortOrder",
"required": false,
"default": "ASC"
}
]
},
"graphql": {
"enabled": true,
"operation": "mutation",
"type": {
"singular": "MyProc",
"plural": "MyProcs"
}
},
"rest": {
"enabled": true,
"methods": [
"post"
]
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
```
**After (expanded array format):**
Add:
```
dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll add entity GetTodosByOwnerAndStatus --source "dbo.GetTodosByOwnerAndStatus" --source.type stored-procedure --parameters.name "OwnerId,Completed" --parameters.description "Owner ID,Completed status" --parameters.required "true,false" --parameters.default "public,0" --permissions "anonymous:execute" --config C:\DAB\data-api-builder\src\Service\dab-config.json
```
Config created:
```
"entity": {
"source": {
"object": "dbo.GetTodosByOwnerAndStatus",
"type": "stored-procedure",
"parameters": [
{
"name": "OwnerId",
"description": "Owner ID",
"required": true,
"default": "public"
},
{
"name": "Completed",
"description": "Completed status",
"required": false,
"default": "0"
}
]
},
"graphql": {
"enabled": true,
"operation": "mutation",
"type": {
"singular": "entity",
"plural": "entities"
}
},
"rest": {
"enabled": true,
"methods": [
"post"
]
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
```
Validate:
```
dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll validate -c "C:\DAB\data-api-builder\src\Service\dab-config.json"
```
Validate when both formats are given:
```
PS C:\DAB\data-api-builder\src\Service> dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll add MyProc --source "dbo.MyProc" --source.type stored-procedure --source.params "PageSize:50,SortOrder:ASC" --permissions "anonymous:execute" "authenticated:execute" --config C:\DAB\data-api-builder\src\Service\dab-config.json --parameters.name "OwnerId,Completed" --parameters.description "Owner ID,Completed status" --parameters.required "true,false" --parameters.default "public,0"
Information: Microsoft.DataApiBuilder 1.7.0
Information: User provided config file: C:\DAB\data-api-builder\src\Service\dab-config.json
Loading config file from C:\DAB\data-api-builder\src\Service\dab-config.json.
Error: Cannot use both --source.params and --parameters.name/description/required/default together. Please use only one format.
Error: Unable to create the source object.
Error: Failed to add a new entity.
Error: Could not add entity: MyProc with source: dbo.MyProc and permissions: anonymous:execute.
```
Update:
```
dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll update entity GetTodosByOwnerAndStatus --parameters.name "OwnerId,Completed" --parameters.description "Owner ID,Completed status" --parameters.required "true,false" --parameters.default "private,protected" --config "C:\DAB\data-api-builder\src\Service\dab-config.json"
```
Config updated:
```
"entity": {
"source": {
"object": "dbo.GetTodosByOwnerAndStatus",
"type": "stored-procedure",
"parameters": [
{
"name": "OwnerId",
"description": "Owner ID",
"required": true,
"default": "private"
},
{
"name": "Completed",
"description": "Completed status",
"required": false,
"default": "protected"
}
]
},
"graphql": {
"enabled": true,
"operation": "mutation",
"type": {
"singular": "entity",
"plural": "entities"
}
},
"rest": {
"enabled": true,
"methods": [
"post"
]
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
```
-----------------------------------------------
Create a stored procedure:
```
CREATE PROCEDURE dbo.InsertTodo
@id UNIQUEIDENTIFIER,
@title NVARCHAR(1000),
@completed BIT = 0,
@owner_id VARCHAR(128),
@position INT = NULL
AS
BEGIN
INSERT INTO dbo.todos (id, title, completed, owner_id, position)
VALUES (@id, @title, @completed, @owner_id, @position);
SELECT id, title, completed, owner_id, position
FROM dbo.todos
WHERE id = @id;
END
GO
```
1. Without providing default parameter values
```
mutation {
executeInsertTodo(
id: "00000000-0000-0000-0000-000000000013",
title: "Test DAB GraphQL",
owner_id: "Anusha Kolan"
# completed and position are optional
) {
id
title
completed
owner_id
position
}
}
```
Uses DB default values
```
{
"data": {
"executeInsertTodo": [
{
"id": "00000000-0000-0000-0000-000000000013",
"title": "Test DAB GraphQL",
"completed": false,
"owner_id": "Anusha Kolan",
"position": null
}
]
}
}
```
2. With providing default parameter values
```
mutation {
executeInsertTodo(
id: "00000000-0000-0000-0000-000000000014",
title: "Test with completed",
owner_id: "Anusha Kolan",
completed: true,
position: 5
) {
id
title
completed
owner_id
position
}
}
```
Uses the default values provided
```
{
"data": {
"executeInsertTodo": [
{
"id": "00000000-0000-0000-0000-000000000014",
"title": "Test with completed",
"completed": true,
"owner_id": "Anusha Kolan",
"position": 5
}
]
}
}
```
-----------------------------------------------------------------------------------
Config:
```
"InsertTodo": {
"source": {
"object": "dbo.InsertTodo",
"type": "stored-procedure",
"parameters": [
{
"name": "id",
"description": "The id for the Todo.",
"required": true
},
{
"name": "title",
"description": "The title for the Todo.",
"required": true
},
{
"name": "completed",
"description": "The state of the Todo.",
"required": false
},
{
"name": "owner_id",
"required": true
},
{
"name": "position",
"required": false
}
]
},
"graphql": {
"enabled": true,
"operation": "mutation",
"type": {
"singular": "InsertTodo",
"plural": "InsertTodos"
}
},
"rest": {
"enabled": true,
"methods": [
"post"
]
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
```
GraphQL Schema Documentation
```
"Execute Stored-Procedure InsertTodo and get results from the database"
executeInsertTodo(
"The state of the Todo."
completed: Boolean
"The id for the Todo."
id: UUID
"parameters for InsertTodo stored-procedure"
owner_id: String
"parameters for InsertTodo stored-procedure"
position: Int
"The title for the Todo."
title: String
): [InsertTodo!]! @cost(weight: "10")
```
OpenAPI Documentation
```
"InsertTodo_sp_request": {
"required": [
"id",
"owner_id",
"title"
],
"type": "object",
"properties": {
"completed": {
"type": "boolean",
"description": "The state of the Todo."
},
"id": {
"type": "string",
"description": "The id for the Todo."
},
"owner_id": {
"type": "string"
},
"position": {
"type": "number"
},
"title": {
"type": "string",
"description": "The title for the Todo."
}
}
},
```1 parent 505e0c2 commit 4c5038f
34 files changed
Lines changed: 753 additions & 224 deletions
File tree
- schemas
- src
- Azure.DataApiBuilder.Mcp/BuiltInTools
- Cli.Tests
- Snapshots
- Cli
- Commands
- Config
- Converters
- DatabasePrimitives
- ObjectModel
- Core/Services
- MetadataProviders
- OpenAPI
- Service.GraphQLBuilder
- Service.Tests
- GraphQLBuilder
- Helpers
- Sql
- OpenApiDocumentor
- Snapshots
- UnitTests
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
755 | 755 | | |
756 | 756 | | |
757 | 757 | | |
758 | | - | |
759 | | - | |
760 | | - | |
761 | | - | |
762 | | - | |
763 | | - | |
764 | | - | |
765 | | - | |
766 | | - | |
767 | | - | |
768 | | - | |
769 | | - | |
770 | | - | |
| 758 | + | |
| 759 | + | |
| 760 | + | |
| 761 | + | |
| 762 | + | |
| 763 | + | |
| 764 | + | |
| 765 | + | |
| 766 | + | |
| 767 | + | |
| 768 | + | |
771 | 769 | | |
772 | | - | |
| 770 | + | |
| 771 | + | |
| 772 | + | |
| 773 | + | |
| 774 | + | |
| 775 | + | |
| 776 | + | |
| 777 | + | |
| 778 | + | |
| 779 | + | |
| 780 | + | |
| 781 | + | |
| 782 | + | |
| 783 | + | |
| 784 | + | |
773 | 785 | | |
774 | | - | |
| 786 | + | |
775 | 787 | | |
776 | 788 | | |
777 | 789 | | |
| |||
Lines changed: 4 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
169 | 169 | | |
170 | 170 | | |
171 | 171 | | |
172 | | - | |
| 172 | + | |
173 | 173 | | |
174 | 174 | | |
175 | 175 | | |
| |||
205 | 205 | | |
206 | 206 | | |
207 | 207 | | |
208 | | - | |
| 208 | + | |
209 | 209 | | |
210 | | - | |
| 210 | + | |
211 | 211 | | |
212 | | - | |
| 212 | + | |
213 | 213 | | |
214 | 214 | | |
215 | 215 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
45 | 45 | | |
46 | 46 | | |
47 | 47 | | |
48 | | - | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
49 | 53 | | |
50 | | - | |
51 | 54 | | |
52 | 55 | | |
53 | 56 | | |
| |||
75 | 78 | | |
76 | 79 | | |
77 | 80 | | |
78 | | - | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
79 | 86 | | |
80 | 87 | | |
81 | 88 | | |
| |||
107 | 114 | | |
108 | 115 | | |
109 | 116 | | |
110 | | - | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
111 | 122 | | |
112 | 123 | | |
113 | 124 | | |
| |||
143 | 154 | | |
144 | 155 | | |
145 | 156 | | |
146 | | - | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
147 | 162 | | |
148 | 163 | | |
149 | 164 | | |
| |||
174 | 189 | | |
175 | 190 | | |
176 | 191 | | |
177 | | - | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
178 | 197 | | |
179 | 198 | | |
180 | 199 | | |
| |||
211 | 230 | | |
212 | 231 | | |
213 | 232 | | |
214 | | - | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
215 | 238 | | |
216 | 239 | | |
217 | 240 | | |
| |||
244 | 267 | | |
245 | 268 | | |
246 | 269 | | |
247 | | - | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
248 | 275 | | |
249 | 276 | | |
250 | 277 | | |
| |||
276 | 303 | | |
277 | 304 | | |
278 | 305 | | |
279 | | - | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
280 | 311 | | |
281 | 312 | | |
282 | 313 | | |
| |||
304 | 335 | | |
305 | 336 | | |
306 | 337 | | |
307 | | - | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
308 | 343 | | |
309 | 344 | | |
310 | 345 | | |
| |||
359 | 394 | | |
360 | 395 | | |
361 | 396 | | |
362 | | - | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
| 401 | + | |
363 | 402 | | |
364 | 403 | | |
365 | 404 | | |
| |||
419 | 458 | | |
420 | 459 | | |
421 | 460 | | |
422 | | - | |
| 461 | + | |
| 462 | + | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
423 | 466 | | |
424 | 467 | | |
425 | 468 | | |
| |||
455 | 498 | | |
456 | 499 | | |
457 | 500 | | |
458 | | - | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
| 504 | + | |
| 505 | + | |
459 | 506 | | |
460 | 507 | | |
461 | 508 | | |
| |||
494 | 541 | | |
495 | 542 | | |
496 | 543 | | |
497 | | - | |
| 544 | + | |
| 545 | + | |
| 546 | + | |
| 547 | + | |
| 548 | + | |
498 | 549 | | |
499 | 550 | | |
500 | 551 | | |
| |||
Lines changed: 17 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
32 | | - | |
33 | | - | |
34 | | - | |
35 | | - | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
36 | 48 | | |
37 | 49 | | |
38 | 50 | | |
| |||
Lines changed: 17 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
32 | | - | |
33 | | - | |
34 | | - | |
35 | | - | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
36 | 48 | | |
37 | 49 | | |
38 | 50 | | |
| |||
Lines changed: 17 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
35 | 35 | | |
36 | 36 | | |
37 | 37 | | |
38 | | - | |
39 | | - | |
40 | | - | |
41 | | - | |
42 | | - | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
43 | 55 | | |
44 | 56 | | |
45 | 57 | | |
| |||
Lines changed: 17 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
35 | 35 | | |
36 | 36 | | |
37 | 37 | | |
38 | | - | |
39 | | - | |
40 | | - | |
41 | | - | |
42 | | - | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
43 | 55 | | |
44 | 56 | | |
45 | 57 | | |
| |||
Lines changed: 17 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
5 | | - | |
6 | | - | |
7 | | - | |
8 | | - | |
9 | | - | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
10 | 22 | | |
11 | 23 | | |
12 | 24 | | |
| |||
0 commit comments