Data API builder configuration schema reference

Data API builder requires at least one configuration file to run. This JSON-based file defines your API setup, from environment settings to entity definitions. It begins with a $schema property, which enables schema validation for the rest of the file.

Top-level properties

Data-source properties

Runtime properties

Entities properties

Schema

Each configuration file begins with a $schema property, specifying the JSON schema for validation.

Format

{
  "$schema": <string>
}

Example

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

Versioning

Schema files are available at specific URLs, ensuring you can use the correct version or the latest available schema.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

Replace VERSION-suffix with the version you want.

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

Data source files

Data API builder supports multiple configuration files, with one designated as the top-level file managing runtime settings. All configurations share the same JSON schema, allowing runtime settings in any or every file without error. Split entities for better organization.

Format

{
  "data-source-files": [ "<string>" ]
}

Multiple configuration rules

• Every configuration file must include the data-source property.
• Every configuration file must include the entities property (or autoentities).
• The top-level configuration must include runtime.
• Child configurations can include runtime, but Data API builder ignores it.
• Child configuration files can include their own child files.
• Configuration files can be organized into subfolders.
• Entity names must be unique across all configuration files.
• Relationships between entities in different configuration files aren't supported.

Examples

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Autoentities

The autoentities section defines pattern-based rules that automatically expose matching database objects as DAB entities at startup. Each key in the object is a named definition containing patterns, a template, and permissions.

When autoentities is present, the entities section is no longer required. The configuration schema allows either autoentities or entities (or both). If both are present, explicitly defined entities take precedence over autoentities matches with the same name.

Format

{
  "autoentities": {
    "<definition-name>": {
      "patterns": {
        "include": [ "<string>" ],
        "exclude": [ "<string>" ],
        "name": "<string>"
      },
      "template": {
        "mcp": { "dml-tools": <boolean> },
        "rest": { "enabled": <boolean> },
        "graphql": { "enabled": <boolean> },
        "health": { "enabled": <boolean> },
        "cache": {
          "enabled": <boolean>,
          "ttl-seconds": <integer>,
          "level": "<string>"
        }
      },
      "permissions": [
        {
          "role": "<string>",
          "actions": [ { "action": "<string>" } ]
        }
      ]
    }
  }
}

Properties

Example

{
  "autoentities": {
    "my-def": {
      "patterns": {
        "include": [ "dbo.%" ],
        "exclude": [ "dbo.internal%" ],
        "name": "{schema}_{object}"
      },
      "template": {
        "rest": { "enabled": true },
        "graphql": { "enabled": true },
        "cache": { "enabled": true, "ttl-seconds": 30, "level": "l1l2" }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

With this configuration, every table and view in the dbo schema (except those matching dbo.internal%) is automatically exposed as a DAB entity. Each entity is named using the {schema}_{object} pattern (for example, dbo_Products), has REST and GraphQL enabled, uses caching with a 30-second time-to-live (TTL), and grants read access to the anonymous role.

Azure Key Vault

Configures Azure Key Vault integration for managing secrets. When present, the endpoint property is required.

Nested properties

To reference secrets stored in Azure Key Vault, use the @akv() function in your configuration values. Data API builder resolves these references at startup using the configured endpoint.

Format

{
  "azure-key-vault": {
    "endpoint": "<string>",
    "retry-policy": {
      "mode": <"exponential"> (default) | <"fixed">,
      "max-count": <integer; default: 3>,
      "delay-seconds": <integer; default: 1>,
      "max-delay-seconds": <integer; default: 60>,
      "network-timeout-seconds": <integer; default: 60>
    }
  }
}

Example

{
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 120,
      "network-timeout-seconds": 90
    }
  },
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('sql-connection-string')"
  }
}