data-api-builder-config

Data API Builder Configuration

This skill powers GitHub Copilot assistance for Data API Builder (DAB) configuration files. It provides expert guidance on the internal structure, schema validation, and best practices for dab-config.json files to ensure configurations are complete, valid, and aligned with DAB's capabilities.

---

Core Mental Model

DAB is driven entirely by a JSON configuration file (typically dab-config.json). This configuration defines:

1. $schema - JSON schema reference for validation
2. data-source - Database connection and settings
3. data-source-files - Optional array of child configuration files
4. runtime - Global runtime behavior (REST, GraphQL, MCP, auth, caching, telemetry)
5. entities - Database objects exposed as API endpoints

Configuration Philosophy

• Declarative over imperative - Config declares intent, DAB handles implementation
• Security by default - Auth, RBAC, and policies are first-class citizens
• Multi-file support - Large projects can split entities across files
• Environment variable support - Secrets live outside config via @env('VAR_NAME')
• Schema-driven validation - Always validate against JSON schema

Key Constraints

• Entity names must be unique across all configuration files
• Relationships cannot span across different configuration files
• Child configs can include runtime, but it's ignored (only top-level runtime applies)
• Every config file must include both data-source and entities sections
• Connection strings should never contain plain-text secrets in production

---

Configuration File Structure

Minimal Valid Configuration

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "development"
    }
  },
  "entities": {}
}

Full Configuration Anatomy

{
  "$schema": "<schema-url>",
  "data-source": { /* database connection */ },
  "data-source-files": [ /* child config paths */ ],
  "runtime": {
    "pagination": { /* page size limits */ },
    "rest": { /* REST endpoint config */ },
    "graphql": { /* GraphQL endpoint config */ },
    "mcp": { /* MCP endpoint config (v1.7+) */ },
    "host": {
      "mode": "production|development",
      "max-response-size-mb": 158,
      "cors": { /* CORS settings */ },
      "authentication": { /* auth provider config */ }
    },
    "cache": { /* global caching */ },
    "telemetry": { /* logging, tracing, monitoring */ },
    "health": { /* health check settings */ }
  },
  "entities": {
    "{entity-name}": {
      "source": { /* database object details */ },
      "rest": { /* entity-level REST config */ },
      "graphql": { /* entity-level GraphQL config */ },
      "mcp": { /* entity-level MCP config (v1.7+) */ },
      "permissions": [ /* RBAC rules */ ],
      "relationships": { /* entity relationships */ },
      "mappings": { /* field aliasing */ },
      "cache": { /* entity-level caching */ },
      "health": { /* entity-level health checks */ }
    }
  }
}

---

Schema ($root)

Property: $schema
Type: string
Required: ✔️ Yes
Default: None

Purpose

Points to the JSON schema file that validates the configuration structure. Enables IntelliSense in VS Code and other editors.

Format

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json"
}

Versioned Schemas

You can pin to specific DAB versions:

https://github.com/Azure/data-api-builder/releases/download/v{VERSION}-{suffix}/dab.draft.schema.json

Example:

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

Best Practices

• Always use :latest for active development
• Pin to specific version for production stability
• Schema enables editor autocomplete and real-time validation
• Schema violations prevent dab validate from passing

---

Data Source

Property: data-source
Type: object
Required: ✔️ Yes
Default: None

Required Nested Properties

Property	Type	Required	Description
database-type	enum	✔️ Yes	Database engine type
connection-string	string	✔️ Yes	Connection details
options	object	❌ No	Database-specific settings
health	object	❌ No	Data source health check config

Supported Database Types

database-type	Description	Min Version
mssql	Azure SQL, SQL Server, SQL in Fabric	SQL Server 2016+
dwsql	Azure Synapse, Fabric Warehouse, Fabric SQL Analytics	-
postgresql	PostgreSQL	11+
mysql	MySQL	8+
cosmosdb_nosql	Azure Cosmos DB for NoSQL	-
cosmosdb_postgresql	Azure Cosmos DB for PostgreSQL	-

Format

{
  "data-source": {
    "database-type": "mssql|postgresql|mysql|cosmosdb_nosql|cosmosdb_postgresql|dwsql",
    "connection-string": "@env('CONNECTION_STRING')",
    "options": {
      "set-session-context": true,
      "database": "cosmos-db-name",
      "container": "cosmos-container-name",
      "schema": "path/to/schema.graphql"
    },
    "health": {
      "enabled": true,
      "name": "primary-db",
      "threshold-ms": 1000
    }
  }
}

Connection String Best Practices

Development:

{
  "connection-string": "@env('DEV_CONNECTION_STRING')"
}

Production with Managed Identity (Recommended):

Server=tcp:myserver.database.windows.net,1433;Database=mydb;Authentication=Active Directory Managed Identity;

User-Assigned Managed Identity:

Server=tcp:myserver.database.windows.net,1433;Database=mydb;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;

Database-Specific Options

SQL Server (mssql)

Option	Type	Default	Description
set-session-context	boolean	true	Passes JWT claims to SESSION_CONTEXT

Example:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  }
}

Consuming SESSION_CONTEXT in SQL:

CREATE PROC GetUser @userId INT AS
BEGIN
    IF SESSION_CONTEXT(N'user_role') = 'admin'
    BEGIN
        -- Admin-specific logic
    END
    
    SELECT Id, Name FROM Users WHERE Id = @userId;
END

Cosmos DB NoSQL (cosmosdb_nosql)

Option	Type	Required	Description
database	string	✔️ Yes	Cosmos DB database name
container	string	❌ No	Default container name
schema	string	✔️ Yes	Path to GraphQL schema file

Example:

{
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "@env('COSMOS_CONNECTION_STRING')",
    "options": {
      "database": "MyCosmosDatabase",
      "container": "MyContainer",
      "schema": "schema.graphql"
    }
  }
}

Connection Resiliency

DAB automatically retries transient errors using Exponential Backoff:

Attempt	Delay
1st	2s
2nd	4s
3rd	8s
4th	16s
5th	32s

Health Configuration

Property	Type	Default	Description
enabled	boolean	true	Enables health checks for this data source
name	string	database-type	Identifier in health reports
threshold-ms	integer	1000	Max acceptable query duration (ms)

Format:

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 500
    }
  }
}

Common Mistakes

❌ Plain-text secrets in config:

{
  "connection-string": "Server=...;Password=MyPassword123"
}

✅ Use environment variables:

{
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

❌ Missing schema for Cosmos DB NoSQL:

{
  "database-type": "cosmosdb_nosql",
  "connection-string": "@env('COSMOS_STRING')"
  // Missing options.schema!
}

✅ Include required options:

{
  "database-type": "cosmosdb_nosql",
  "connection-string": "@env('COSMOS_STRING')",
  "options": {
    "database": "MyDB",
    "schema": "schema.graphql"
  }
}

---

Data Source Files

Property: data-source-files
Type: string array
Required: ❌ No
Default: None

Purpose

Allows splitting configuration across multiple files for better organization. Useful for large projects with many entities.

Format

{
  "data-source-files": [
    "dab-config-users.json",
    "entities/products.json",
    "entities/orders/config.json"
  ]
}

Multi-File Configuration Rules

MUST:

• Every config file must include data-source
• Every config file must include entities
• Top-level config must include runtime
• Entity names must be unique across all files

MAY:

• Child configs can include runtime (ignored)
• Child configs can include their own child files
• Files can be organized in subfolders

CANNOT:

• Define relationships between entities in different files

Example: Multi-File Structure

dab-config.json (top-level):

{
  "$schema": "...",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('CONNECTION_STRING')"
  },
  "data-source-files": [
    "entities/users-config.json",
    "entities/products-config.json"
  ],
  "runtime": {
    "host": { "mode": "production" }
  },
  "entities": {
    "HealthCheck": {
      "source": { "object": "dbo.HealthCheck", "type": "table" },
      "permissions": [{ "role": "anonymous", "act

---

*Content truncated.*