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.

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