[MCP] Added fields section for entities and backward compatibility to mappings and key-fields.

[anushakolan]

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?

All automated tests have been executed, updated as necessary, and completed successfully.

Manually tested with following queries:

1. 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]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[RubenCerna2079]

LGTM!

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).