[MCP] Added fields section for entities #2916

anushakolan · 2025-10-21T08:39:00Z

Why make this change?

This change introduces richer metadata for entity fields and keys in the Data API Builder configuration. The goal is to enable semantic metadata for documentation, client generation, and MCP tools, and to begin deprecating the legacy mappings and source.key-fields properties.

What is this change?

Introduces a new fields property for entities in the config schema.
Each field supports:
- name: database column name (required)
- alias: exposed name for the field (optional)
- description: field description (optional)
- primary-key: whether the field is a primary key (optional)
Updates the JSON schema to enforce that fields cannot be used with legacy mappings or source.key-fields.
Updates CLI commands (dab add, dab update) to support specifying field alias, description, and primary-key.
Updates dab validate to warn if fields are missing and MCP is enabled.
Updates OpenAPI, GraphQL, and MCP describe_entities responses to include field descriptions.
Adds auto-migration logic to convert legacy mappings and source.key-fields to the new fields format when relevant CLI flags are used.
Maintains backward compatibility: legacy properties are still supported, but validation enforces that fields and legacy props are not mixed.

How was this tested?

Manually tested with following queries:

Update Entity with Field Mappings and Key Fields
dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll update BookAuthor --map "BookID:book_id,AuthorID:author_id" --source.key-fields "BookID,AuthorID" --config "C:\DAB\data-api-builder\src\Service\dab-config.json"

Validate the Configuration

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"

Update Entity Field Metadata (Primary Key)

dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll update Todo --fields.name owner_id --fields.primary-key True --config C:\DAB\data-api-builder\src\Service\dab-config.json

Update Entity Key Fields Only

dotnet C:\DAB\data-api-builder\src\out\cli\net8.0\Microsoft.DataApiBuilder.dll update BookAuthor --source.key-fields "BookID"

Sample new format

"fields": [ { "name": "id", "alias": "id", "description": "The unique identifier for a todo item", "primary-key": true }, { "name": "title", "alias": "title", "description": "The title of the todo item", "primary-key": false }, { "name": "completed", "alias": "completed", "description": "Indicates whether the todo item is completed", "primary-key": false }, { "name": "owner_id", "alias": "owner", "description": "Hello", "primary-key": true }, { "name": "position", "alias": "position", "description": "The position of the todo item in the list", "primary-key": false } ],

GraphQL Introspection Example

Query

{ __type(name: "Todo") { name description fields { name description } } }

Result
{ "data": { "__type": { "name": "Todo", "description": "Represents a todo item in the system", "fields": [ { "name": "id", "description": "The unique identifier for a todo item" }, { "name": "title", "description": "The title of the todo item" }, { "name": "completed", "description": "Indicates whether the todo item is completed" }, { "name": "owner", "description": "Hello" }, { "name": "position", "description": "The position of the todo item in the list" } ] } } }

OpenAPI Schema Example

"Todo": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for a todo item", "format": "" }, "title": { "type": "string", "description": "The title of the todo item", "format": "" }, "completed": { "type": "boolean", "description": "Indicates whether the todo item is completed", "format": "" }, "owner_id": { "type": "string", "description": "Hello", "format": "" }, "position": { "type": "number", "description": "The position of the todo item in the list", "format": "" } }, "description": "Represents a todo item in the system" }

anushakolan · 2025-10-21T08:39:11Z

/azp run

azure-pipelines · 2025-10-21T08:39:35Z

Azure Pipelines successfully started running 6 pipeline(s).

Copilot

Pull Request Overview

This PR introduces a new fields section for entities as part of the Model Context Protocol (MCP) implementation. The change consolidates the legacy mappings and key-fields properties into a unified fields array that provides richer metadata (aliases, descriptions, primary key designation) for entity columns.

Key Changes

Added FieldMetadata class to represent field-level configuration including name, alias, description, and primary key status
Updated Entity constructor and configuration to include optional Fields property
Modified CLI commands to support field configuration through new command-line options
Converted legacy mappings and key-fields usage to the new fields structure in update operations

Reviewed Changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Config/ObjectModel/FieldMetadata.cs	New class defining field metadata structure
src/Config/ObjectModel/Entity.cs	Added Fields property to Entity record
src/Cli/ConfigGenerator.cs	Implemented field validation, conversion from legacy properties, and MCP-related warnings
src/Cli/Commands/EntityOptions.cs	Added CLI options for field configuration
src/Cli/Commands/AddOptions.cs	Updated constructor to accept field-related parameters
src/Cli/Commands/UpdateOptions.cs	Updated constructor to accept field-related parameters
src/Service.GraphQLBuilder/Sql/SchemaConverter.cs	Updated to use Fields instead of Mappings for aliases and descriptions
src/Core/Services/OpenAPI/OpenApiDocumentor.cs	Enhanced to include field descriptions from Fields metadata
src/Core/Services/MetadataProviders/SqlMetadataProvider.cs	Updated GraphQL reserved name checking to use Fields; removed unused helper method
src/Core/Services/MetadataProviders/MsSqlMetadataProvider.cs	Added Fields: null to linking entity creation
schemas/dab.draft.schema.json	Added schema definition for fields array with mutual exclusivity constraints
Multiple test files	Updated test entity instantiations to include Fields: null parameter
Multiple snapshot files	Updated snapshots showing conversion of mappings/key-fields to Fields structure

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/Service.Tests/UnitTests/RequestValidatorUnitTests.cs

src/Cli/ConfigGenerator.cs

Copilot · 2025-10-21T08:40:15Z

schemas/dab.draft.schema.json

+                "not": {
+                  "anyOf": [
+                    { "required": ["mappings"] },
+                    { "properties": { "source": { "properties": { "key-fields": { } }, "required": ["key-fields"] } } }


The JSON schema constraint to prevent fields and key-fields coexistence is incorrect. The nested structure doesn't properly check for the presence of key-fields in the source object. It should be: { \"properties\": { \"source\": { \"required\": [\"key-fields\"] } } }.

Suggested change

{ "properties": { "source": { "properties": { "key-fields": { } }, "required": ["key-fields"] } } }

{ "properties": { "source": { "required": ["key-fields"] } } }

anushakolan · 2025-10-21T08:50:23Z

One pending follow up task, is to check if the given field is a valid column in the entity. Will add this check as part of a follow up PR.

anushakolan · 2025-10-21T09:43:19Z

/azp run

azure-pipelines · 2025-10-21T09:43:42Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2025-10-21T20:11:52Z

/azp run

azure-pipelines · 2025-10-21T20:12:15Z

Azure Pipelines successfully started running 6 pipeline(s).

Aniruddh25 · 2025-10-21T23:01:00Z

...UpdateEntityTests.TestUpdateSourceStringToDatabaseSourceObject_574e1995f787740f.verified.txt

-          ]
+          Type: View
        },
+        Fields: [


We should ensure the new fields section is well-documented. Please create a doc task for @JerryNixon

anushakolan · 2025-10-22T00:21:10Z

/azp run

azure-pipelines · 2025-10-22T00:21:31Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2025-10-22T00:26:30Z

/azp run

azure-pipelines · 2025-10-22T00:26:52Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2025-10-22T01:03:56Z

/azp run

azure-pipelines · 2025-10-22T01:04:21Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2025-10-22T04:03:28Z

/azp run

azure-pipelines · 2025-10-22T04:03:50Z

Azure Pipelines successfully started running 6 pipeline(s).

souvikghosh04 · 2025-10-22T09:31:54Z

/azp run

azure-pipelines · 2025-10-22T09:32:02Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

souvikghosh04 · 2025-10-22T09:32:34Z

/azp run

RubenCerna2079 · 2025-10-23T22:39:02Z

schemas/dab.draft.schema.json

+                  "name": { "type": "string", "description": "Database column name." },
+                  "alias": { "type": "string", "description": "Exposed name for the field." },
+                  "description": { "type": "string", "description": "Field description." },
+                  "primary-key": { "type": "boolean", "description": "Is this field a primary key?" }


Is this a question for someone? I think we should change this description

RubenCerna2079 · 2025-10-23T22:54:03Z

...UpdateEntityTests.TestUpdateSourceStringToDatabaseSourceObject_a13a9ca73b21f261.verified.txt

        Source: {
          Object: s001.book,
-          Type: Table,
-          KeyFields: [


Is KeyFields a different name for mappings just to specify that it is a primary key? Please also mention this parameter in the PR description

RubenCerna2079 · 2025-10-23T22:59:10Z

src/Cli.Tests/AddEntityTests.cs

+                fieldsNameCollection: [],
+                fieldsAliasCollection: [],
+                fieldsDescriptionCollection: [],
+                fieldsPrimaryKeyCollection: []


Is there a reason to make these parameters empty and not null?

The same question applies to the other instances where this change was made.

RubenCerna2079 · 2025-10-23T23:02:04Z

src/Cli/Commands/EntityOptions.cs

+            string? config
+            )


nit:

Suggested change

string? config

)

string? config)

RubenCerna2079 · 2025-10-24T01:26:32Z

src/Cli/ConfigGenerator.cs

+            else
+            {
+                fields = [];
+                _logger.LogWarning("Using legacy 'mappings' and 'key-fields' properties. Consider using 'fields' for new entities.");


I think this warning should be in the else if (hasMappings || hasKeyFields) section

RubenCerna2079 · 2025-10-24T01:46:15Z

src/Core/Services/MetadataProviders/SqlMetadataProvider.cs

+                    // Resolve PKs from fields first
+                    List<string>? pkFields = entity.Fields?
+                        .Where(f => f.PrimaryKey)
+                        .Select(f => f.Name)
+                        .ToList();
+
+                    // Fallback to key-fields from config
+                    if (pkFields == null || pkFields.Count == 0)
+                    {
+                        pkFields = entity.Source.KeyFields?.ToList();
+                    }
+
+                    // If still empty, fallback to DB schema PKs
+                    if (pkFields == null || pkFields.Count == 0)
+                    {
+                        DataTable dataTable = await GetTableWithSchemaFromDataSetAsync(
+                            entityName,
+                            GetSchemaName(entityName),
+                            GetDatabaseObjectName(entityName));
+
+                        pkFields = dataTable.PrimaryKey.Select(pk => pk.ColumnName).ToList();
+                    }


I see that this code is the same as the one above. Couldn't we make a helper function out of it in order to not have repeated code?

anushakolan · 2025-10-24T08:00:42Z

/azp run

azure-pipelines · 2025-10-24T08:00:49Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

Copilot AI review requested due to automatic review settings October 21, 2025 08:39

anushakolan requested review from Alekhya-Polavarapu, Aniruddh25, RubenCerna2079, aaronburtle, neeraj-sharma2592, rusamant, sourabh1007, souvikghosh04 and vadeveka as code owners October 21, 2025 08:39

Copilot AI reviewed Oct 21, 2025

View reviewed changes

Aniruddh25 reviewed Oct 21, 2025

View reviewed changes

anushakolan added 25 commits October 22, 2025 15:12

Added field section for entities

1dd9f0f

Fotmat fix

49e6ec2

Test fix

aa5472a

Test fix

3d66a13

Fix test

16e11fe

Added debuglogs

c1e43d0

Added debuglogs 2

5493ef8

Added debug logs

496ca62

Added debuglogs 3

e3d5955

Added debuglogs 4

efe9d92

Added debuglogs 5

474aaf5

Main bug fix

84b588b

Main bug fix 2

90388ee

Test fix

939c038

Added updated postgres snapshot

5921193

test fix

de7fc51

Test Fixes

49dd3cc

Major bug fix regarding pk alias issue

c5558c9

Bug fixes

d7253e7

Bug fix

713a1f9

Fix

9b2cf6d

fix 2

6b7f62c

Cleanup

61a0d2d

Cleanup 1

3de8575

Cleanup 3

66e5e79

RubenCerna2079 reviewed Oct 24, 2025

View reviewed changes

Test fix

89dd7f3

anushakolan force-pushed the dev/anushakolan/mcp/add-field-description branch from 0045c97 to 89dd7f3 Compare October 24, 2025 07:58

	{ "properties": { "source": { "properties": { "key-fields": { } }, "required": ["key-fields"] } } }
	{ "properties": { "source": { "required": ["key-fields"] } } }

Uh oh!

[MCP] Added fields section for entities #2916

Are you sure you want to change the base?

[MCP] Added fields section for entities #2916

Uh oh!

Conversation

anushakolan commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

What is this change?

How was this tested?

Uh oh!

anushakolan commented Oct 21, 2025

Uh oh!

azure-pipelines bot commented Oct 21, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

anushakolan commented Oct 21, 2025

Uh oh!

anushakolan commented Oct 21, 2025

Uh oh!

azure-pipelines bot commented Oct 21, 2025

Uh oh!

anushakolan commented Oct 21, 2025

Uh oh!

azure-pipelines bot commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anushakolan commented Oct 22, 2025

Uh oh!

azure-pipelines bot commented Oct 22, 2025

Uh oh!

anushakolan commented Oct 22, 2025

Uh oh!

azure-pipelines bot commented Oct 22, 2025

Uh oh!

anushakolan commented Oct 22, 2025

Uh oh!

azure-pipelines bot commented Oct 22, 2025

Uh oh!

anushakolan commented Oct 22, 2025

Uh oh!

azure-pipelines bot commented Oct 22, 2025

Uh oh!

souvikghosh04 commented Oct 22, 2025

Uh oh!

azure-pipelines bot commented Oct 22, 2025

Uh oh!

souvikghosh04 commented Oct 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anushakolan commented Oct 24, 2025

Uh oh!

azure-pipelines bot commented Oct 24, 2025

Uh oh!

anushakolan commented Oct 21, 2025 •

edited

Loading