Edit

Share via

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

Property Description
$schema URI of the JSON schema for this configuration.
data-source Object containing database connectivity settings.
data-source-files Array of other configuration file paths.
runtime Object configuring runtime behaviors.
entities Object defining all entities exposed via REST or GraphQL.

Data-source properties

Property Description
data-source Object containing database connectivity settings.
data-source.database-type Database type used in the backend (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql).
data-source.connection-string Connection string for the selected database type.
data-source.options Database-specific options and advanced settings.
data-source.health Health check configuration for the data source.
data-source-files Array of other configuration file paths.

Runtime properties

Property Description
runtime Object configuring runtime behaviors.
runtime.pagination Pagination settings for API responses.
runtime.rest REST API global configuration.
runtime.graphql GraphQL API global configuration.
runtime.cache Global response caching configuration.
runtime.telemetry Telemetry, logging, and monitoring configuration.
runtime.health Global health check configuration.

Entities properties

Property Description
entities Object defining all entities exposed via REST or GraphQL.
entities.entity-name.source Database source details for the entity.
entities.entity-name.rest REST API configuration for the entity.
entities.entity-name.graphql GraphQL API configuration for the entity.
entities.entity-name.permissions Permissions and access control for the entity.
entities.entity-name.relationships Relationships to other entities.
entities.entity-name.cache Entity-level caching configuration.
entities.entity-name.health Entity-level health check configuration.

Schema

Parent Property Type Required Default
$root $schema string ✔️ Yes None

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"
}

Tip

The latest schema is always available at 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

Parent Property Type Required Default
$root data-source-files string array ❌ No None

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.

Diagram of multiple configuration files referenced as an array within a single configuration file.

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.
  • The top-level configuration must include runtime.
  • Child configurations can include runtime, but it's ignored.
  • 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"
  ]
}