Data API builder configuration schema reference
The Data API builder's engine requires a configuration file. The Data API Builder configuration file provides a structured and comprehensive approach to setting up your API, detailing everything from environmental variables to entity-specific configurations. This JSON-formatted document begins with a $schema property. This setup validates the document.
The properties database-type and connection-string ensure seamless integration with database systems, from Azure SQL Database to Cosmos DB NoSQL API.
The configuration file can include options such as:
- Database service and connection information
- Global and runtime configuration options
- Set of exposed entities
- Authentication method
- Security rules required to access identities
- Name mapping rules between API and database
- Relationships between entities that can't be inferred
- Unique features for specific database services
Syntax overview
Here's a quick breakdown of the primary "sections" in a configuration file.
{
"$schema": "...",
"data-source": { ... },
"data-source-files": [ ... ],
"runtime": {
"rest": { ... },
"graphql": { .. },
"host": { ... },
"cache": { ... },
"telemetry": { ... },
"pagination": { ... }
}
"entities": [ ... ]
}
Top-level properties
Here's the description of the top-level properties in a table format:
| Property | Description |
|---|---|
| $schema | Specifies the JSON schema for validation, ensuring the configuration adheres to the required format. |
| data-source | Contains the details about the database type and the connection string, necessary for establishing the database connection. |
| data-source-files | An optional array specifying other configuration files that might define other data sources. |
| runtime | Configures runtime behaviors and settings, including subproperties for REST, GraphQL, host, cache, and telemetry. |
| entities | Defines the set of entities (database tables, views, etc.) that are exposed through the API, including their mappings, permissions, and relationships. |
Sample configurations
Here's a sample configuration file that only includes required properties for a single simple entity. This sample is intended to illustrate a minimal scenario.
{
"$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
"data-source": {
"database-type": "mssql",
"connection-string": "@env('sql-connection-string')"
},
"entities": {
"Book": {
"source": "dbo.books",
"permissions": [{
"actions": ["*"],
"role": "anonymous"
}]
}
}
}
For an example of a more complex scenario, see the end-to-end sample configuration.
Environments
Data API builder's configuration file can support scenarios where you need to support multiple environments, similar to the appSettings.json file in ASP.NET Core. The framework provides three common environment values; Development, Staging, and Production; but you can elect to use any environment value you choose. The environment that Data API builder uses must be configured using the DAB_ENVIRONMENT environment variable.
Consider an example where you want a baseline configuration and a development-specific configuration. This example requires two configuration files:
| Environment | |
|---|---|
| dab-config.json | Base |
| dab-config.Development.json | Development |
To use the development-specific configuration, you must set the DAB_ENVIRONMENT environment variable to Development.
Environment-specific configuration files override property values in the base configuration file. In this example, if the connection-string value is set in both files, the value from the *.Development.json file is used.
Refer to this matrix to better understand which value is used depending on where that value is specified (or not specified) in either file.
| Specified in base configuration | Not specified in base configuration | |
|---|---|---|
| Specified in current environment configuration | Current environment | Current environment |
| Not specified in current environment configuration | Base | None |
For an example of using multiple configuration files, see use Data API builder with environments.
Configuration properties
This section includes all possible configuration properties that are available for a configuration file.
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>
}
Examples
Schema files are available for versions 0.3.7-alpha onwards at specific URLs, ensuring you 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
The latest version of the schema is always available at https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.
Here are a few examples of valid schema values.
| Version | URI | Description |
|---|---|---|
| 0.3.7-alpha | https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json |
Uses the configuration schema from an alpha version of the tool. |
| 0.10.23 | https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json |
Uses the configuration schema for a stable release of the tool. |
| Latest | https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json |
Uses the latest version of the configuration schema. |
Note
Versions of the Data API builder prior to 0.3.7-alpha may have a different schema URI.
Data source
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
$root |
data-source |
string | ✔️ Yes | None |
The data-source section defines the database and access to the database through the connection string. It also defines database options. The data-source property configures the credentials necessary to connect to the backing database. The data-source section outlines backend database connectivity, specifying both the database-type and connection-string.
Format
{
"data-source": {
"database-type": <string>,
"connection-string": <string>,
// mssql-only
"options": {
"set-session-context": <true> (default) | <false>
},
// cosmosdb_nosql-only
"options": {
"database": <string>,
"container": <string>,
"schema": <string>
}
}
}
Properties
| Required | Type | |
|---|---|---|
database-type |
✔️ Yes | enum string |
connection-string |
✔️ Yes | string |
options |
❌ No | object |
Database type
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
data-source |
database-type |
enum-string | ✔️ Yes | None |
An enum string used to specify the type of database to use as the data source.
Format
{
"data-source": {
"database-type": <string>
}
}
Type values
The type property indicates the kind of backend database.
| Type | Description | Min Version |
|---|---|---|
mssql |
Azure SQL Database | None |
mssql |
Azure SQL MI | None |
mssql |
SQL Server | SQL 2016 |
sqldw |
Azure SQL Data Warehouse | None |
postgresql |
PostgreSQL | v11 |
mysql |
MySQL | v8 |
cosmosdb_nosql |
Azure Cosmos DB for NoSQL | None |
cosmosdb_postgresql |
Azure Cosmos DB for PostgreSQL | None |
Connection string
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
data-source |
connection-string |
string | ✔️ Yes | None |
A string value containing a valid connection string to connect to the target database service. The ADO.NET connection string to connect to the backend database. For more information, see ADO.NET connection strings.
Format
{
"data-source": {
"connection-string": <string>
}
}
Connection resiliency
Data API builder automatically retries database requests after detecting transient errors. The retry logic follows an Exponential Backoff strategy where the maximum number of retries is five. The retry backoff duration after subsequent requests is calculated using this formula (assuming the current retry attempt is r): $r^2$
Using this formula, you can calculate the time for each retry attempt in seconds.
| Seconds | |
|---|---|
| First | 2 |
| Second | 4 |
| Third | 8 |
| Fourth | 16 |
| Fifth | 32 |
Azure SQL and SQL Server
Data API builder uses the SqlClient library to connect to Azure SQL or SQL Server using the connection string you provide in the configuration file. A list of all the supported connection string options is available here: SqlConnection.ConnectionString Property.
Data API builder can also connect to the target database using Managed Service Identities (MSI) when Data API builder is hosted in Azure. The DefaultAzureCredential defined in Azure.Identity library is used to connect using known identities when you don't specify a username or password in your connection string. For more information, see DefaultAzureCredential examples.
- User Assigned Managed Identity (UMI): Append the Authentication and User Id properties to your connection string while substituting in your User Assigned Managed Identity's client id:
Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;. - System Assigned Managed Identity (SMI): Append the Authentication property and exclude the UserId and Password arguments from your connection string:
Authentication=Active Directory Managed Identity;. The absence of the UserId and Password connection string properties will signal DAB to authenticate using a system assigned managed identity.
For more information about configuring a Managed Service Identity with Azure SQL or SQL Server, see Managed identities in Microsoft Entra for Azure SQL.
Examples
The value used for the connection string largely depends on the database service used in your scenario. You can always elect to store the connection string in an environment variable and access it using the @env() function.
| Value | Description | |
|---|---|---|
| Use Azure SQL Database string value | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>; |
Connection string to an Azure SQL Database account. For more information, see Azure SQL Database connection strings. |
| Use Azure Database for PostgreSQL string value | Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require; |
Connection string to an Azure Database for PostgreSQL account. For more information, see Azure Database for PostgreSQL connection strings. |
| Use Azure Cosmos DB for NoSQL string value | AccountEndpoint=<endpoint>;AccountKey=<key>; |
Connection string to an Azure Cosmos DB for NoSQL account. For more information, see Azure Cosmos DB for NoSQL connection strings. |
| Use Azure Database for MySQL string value | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>; |
Connection string to an Azure Database for MySQL account. For more information, see Azure Database for MySQL connection strings. |
| Access environment variable | @env('database-connection-string') |
Access an environment variable from the local machine. In this example, the database-connection-string environment variable is referenced. |
Tip
As a best practice, avoid storing sensitive information in your configuration file. When possible, use @env() to reference environment variables. For more information, see @env() function.
These samples just illustrate how each database type might be configured. Your scenario might be unique, but this sample is a good starting place. Replace the placeholders such as myserver, myDataBase, mylogin, and myPassword with the actual values specific to your environment.
mssql"data-source": { "database-type": "mssql", "connection-string": "$env('my-connection-string')", "options": { "set-session-context": true } }- Typical connection string format:
"Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
- Typical connection string format:
postgresql"data-source": { "database-type": "postgresql", "connection-string": "$env('my-connection-string')" }- Typical connection string format:
"Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
- Typical connection string format:
mysql"data-source": { "database-type": "mysql", "connection-string": "$env('my-connection-string')" }- Typical connection string format:
"Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"
- Typical connection string format:
cosmosdb_nosql"data-source": { "database-type": "cosmosdb_nosql", "connection-string": "$env('my-connection-string')", "options": { "database": "Your_CosmosDB_Database_Name", "container": "Your_CosmosDB_Container_Name", "schema": "Path_to_Your_GraphQL_Schema_File" } }- Typical connection string format:
"AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"
- Typical connection string format:
cosmosdb_postgresql"data-source": { "database-type": "cosmosdb_postgresql", "connection-string": "$env('my-connection-string')" }- Typical connection string format:
"Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"
- Typical connection string format:
Note
The "options" specified such as database, container, and schema are specific to Azure Cosmos DB's NoSQL API rather than the PostgreSQL API. For Azure Cosmos DB using the PostgreSQL API, the "options" would not include database, container, or schema as in the NoSQL setup.
Options
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
data-source |
options |
object | ❌ No | None |
An optional section of extra key-value parameters for specific database connections.
Format
{
"data-source": {
"options": {
"<key-name>": <string>
}
}
}
Examples
Whether the options section is required or not is largely dependent on the database service being used.
| Value | Description | |
|---|---|---|
Enable SESSION_CONTEXT in Azure SQL or SQL Server |
"set-session-context": false |
For Azure SQL and SQL Server, Data API builder can take advantage of SESSION_CONTEXT to send user specified metadata to the underlying database. Such metadata is available to Data API builder by virtue of the claims present in the access token. The SESSION_CONTEXT data is available to the database during the database connection until that connection is closed. For more information, see session context. |
{
"data-source"{
"options": {
"set-session-context": false
}
}
}
Data source files
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
$root |
data-source-files |
string array | ❌ No | None |
Data API builder supports multiple configuration files for different data sources, with one designated as the top-level file managing runtime settings. All configurations share the same schema, allowing runtime settings in any file without errors. Child configurations merge automatically, but circular references should be avoided. Entities can be split into separate files for better management, but relationships between entities must be in the same file.
Format
{
"data-source-files": [ <string> ]
}
Configuration file considerations
- Every configuration file must include the
data-sourceproperty. - Every configuration file must include the
entitiesproperty. - The
runtimesetting is only used from the top-level configuration file, even if included in other files. - Child configuration files can also include their own child files.
- Configuration files can be organized into subfolders as desired.
- 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"
]
}
{
"data-source-files": [
"dab-config-2.json",
"dab-config-3.json"
]
}
Subfolder syntax is also supported:
{
"data-source-files": [
"dab-config-2.json",
"my-folder/dab-config-3.json",
"my-folder/my-other-folder/dab-config-4.json"
]
}
Runtime
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
$root |
runtime |
object | ✔️ Yes | None |
The runtime section outlines options that influence the runtime behavior and settings for all exposed entities.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api),
"enabled": <true> (default) | <false>,
"request-body-strict": <true> (default) | <false>
},
"graphql": {
"path": <string> (default: /graphql),
"enabled": <true> (default) | <false>,
"allow-introspection": <true> (default) | <false>
},
"host": {
"mode": "production" (default) | "development",
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
},
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
},
"cache": {
"enabled": <true> | <false> (default),
"ttl-seconds": <integer; default: 5>
},
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>,
"max-response-size-mb": <integer; default: 158>
},
"telemetry": {
"application-insights": {
"connection-string": <string>,
"enabled": <true> | <false> (default)
}
}
}
Properties
| Required | Type | |
|---|---|---|
rest |
❌ No | object |
graphql |
❌ No | object |
host |
❌ No | object |
cache |
❌ No | object |
Examples
Here's an example of a runtime section with multiple common default parameters specified.
{
"runtime": {
"rest": {
"enabled": true,
"path": "/api",
"request-body-strict": true
},
"graphql": {
"enabled": true,
"path": "/graphql",
"allow-introspection": true
},
"host": {
"mode": "development",
"cors": {
"allow-credentials": false,
"origins": [
"*"
]
},
"authentication": {
"provider": "StaticWebApps",
"jwt": {
"audience": "<client-id>",
"issuer": "<identity-provider-issuer-uri>"
}
}
},
"cache": {
"enabled": true,
"ttl-seconds": 5
},
"pagination": {
"max-page-size": -1 | <integer; default: 100000>,
"default-page-size": -1 | <integer; default: 100>,
"max-response-size-mb": <integer; default: 158>
},
"telemetry": {
"application-insights": {
"connection-string": "<connection-string>",
"enabled": true
}
}
}
}
GraphQL (runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
graphql |
object | ❌ No | None |
This object defines whether GraphQL is enabled and the name[s] used to expose the entity as a GraphQL type. This object is optional and only used if the default name or settings aren't sufficient. This section outlines the global settings for the GraphQL endpoint.
Format
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql),
"enabled": <true> (default) | <false>,
"depth-limit": <integer; default: none>,
"allow-introspection": <true> (default) | <false>,
"multiple-mutations": <object>
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
❌ No | boolean | True |
path |
❌ No | string | /graphql (default) |
allow-introspection |
❌ No | boolean | True |
multiple-mutations |
❌ No | object | { create: { enabled: false } } |
Enabled (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql |
enabled |
boolean | ❌ No | None |
Defines whether to enable or disable the GraphQL endpoints globally. If disabled globally, no entities would be accessible via GraphQL requests irrespective of the individual entity settings.
Format
{
"runtime": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
Examples
In this example, the GraphQL endpoint is disabled for all entities.
{
"runtime": {
"graphql": {
"enabled": false
}
}
}
Depth limit (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql |
depth-limit |
integer | ❌ No | None |
The maximum allowed query depth of a query.
GraphQL’s ability to handle nested queries based on relationship definitions is an incredible feature, enabling users to fetch complex, related data in a single query. However, as users continue to add nested queries, the complexity of the query increases, which can eventually compromise the performance and reliability of both the database and the API endpoint. To manage this situation, the runtime/graphql/depth-limit property sets the maximum allowed depth of a GraphQL query (and mutation). This property allows developers to strike a balance, enabling users to enjoy the benefits of nested queries while placing limits to prevent scenarios that could jeopardize the performance and quality of the system.
Examples
{
"runtime": {
"graphql": {
"depth-limit": 2
}
}
}
Path (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql |
path |
string | ❌ No | "/graphql" |
Defines the URL path where the GraphQL endpoint is made available. For example, if this parameter is set to /graphql, the GraphQL endpoint is exposed as /graphql. By default, the path is /graphql.
Important
Sub-paths are not allowed for this property. A customized path value for the GraphQL endpoint isn't currently available.
Format
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql)
}
}
}
Examples
In this example, the root GraphQL URI is /query.
{
"runtime": {
"graphql": {
"path": "/query"
}
}
}
Allow introspection (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql |
allow-introspection |
boolean | ❌ No | True |
This Boolean flag controls the ability to perform schema introspection queries on the GraphQL endpoint. Enabling introspection allows clients to query the schema for information about the types of data available, the kinds of queries they can perform, and the mutations available.
This feature is useful during development for understanding the structure of the GraphQL API and for tooling that automatically generates queries. However, for production environments, it might be disabled to obscure the API's schema details and enhance security. By default, introspection is enabled, allowing for immediate and comprehensive exploration of the GraphQL schema.
Format
{
"runtime": {
"graphql": {
"allow-introspection": <true> (default) | <false>
}
}
}
Examples
In this example, the introspection is disabled.
{
"runtime": {
"graphql": {
"allow-introspection": false
}
}
}
Multiple mutations (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql |
multiple-mutations |
object | ❌ No | None |
Configures all multiple mutation operations for the GraphQL runtime.
Note
By default, multiple mutations is not enabled and must explicitly be configured to be enabled.
Format
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Properties
| Required | Type | |
|---|---|---|
create |
❌ No | object |
Multiple mutations - create (GraphQL runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.graphql.multiple-mutations |
create |
boolean | ❌ No | False |
Configures multiple create operations for the GraphQL runtime.
Format
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
✔️ Yes | boolean | True |
Examples
In this example, multiple mutations are enabled for the GraphQL runtime. Specifically, the multiple create operation is enabled by specifying a value of true for the runtime.graphql.multiple-mutations.create.enabled property.
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": true
}
}
}
}
}
REST (runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
rest |
object | ❌ No | None |
This section outlines the global settings for the REST endpoints. These settings serve as defaults for all entities but can be overridden on a per-entity basis in their respective configurations.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api),
"enabled": <true> (default) | <false>,
"request-body-strict": <true> (default) | <false>
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
❌ No | boolean | True |
path |
❌ No | string | /api |
request-body-strict |
❌ No | boolean | True |
Enabled (REST runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.rest |
enabled |
boolean | ❌ No | None |
A Boolean flag that determines the global availability of REST endpoints. If disabled, entities can't be accessed via REST, regardless of individual entity settings.
Format
{
"runtime": {
"rest": {
"enabled": <true> (default) | <false>,
}
}
}
Examples
In this example, the REST API endpoint is disabled for all entities.
{
"runtime": {
"rest": {
"enabled": false
}
}
}
Path (REST runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.rest |
path |
string | ❌ No | "/api" |
Sets the URL path for accessing all exposed REST endpoints. For instance, setting path to /api makes the REST endpoint accessible at /api/<entity>. Subpaths aren't permitted. This field is optional, with /api as the default.
Note
When deploying Data API builder using Static Web Apps (preview), the Azure service automatically injects the additional subpath /data-api to the url. This behavior ensures compatibility with existing Static Web App features. The resulting endpoint would be /data-api/api/<entity>. This is only relevant to Static Web Apps.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api)
}
}
}
Important
User supplied sub-paths are not allowed for this property.
Examples
In this example, the root REST API URI is /data.
{
"runtime": {
"rest": {
"path": "/data"
}
}
}
Tip
If you define an Author entity, the endpoint for this entity would be /data/Author.
Request body strict (REST runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.rest |
request-body-strict |
boolean | ❌ No | True |
This boolean flag determines whether the request body for a REST mutation operation can contain extraneous fields. By default, the value is true, meaning that extra fields in the request body results in a BadRequest exception. However, setting this flag to false allows users to include extra fields in the request body, which are ignored. It's important to note that this flag doesn't affect REST query (GET) requests, as the request body is always ignored for GET operations.
Note
This flag does not affect HTTP GET requests to the REST API endpoint. The request body is always ignored for GET operations.
Format
{
"runtime": {
"rest": {
"request-body-strict": <true> (default) | <false>
}
}
}
Examples
In this example, strict request body validation is disabled.
{
"runtime": {
"rest": {
"request-body-strict": false
}
}
}
Host (runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
host |
object | ❌ No | None |
The host section within the runtime configuration provides settings crucial for the operational environment of the Data API builder. These settings include operational modes, CORS configuration, and authentication details.
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development",
"max-response-size-mb": <integer; default: 158>,
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
},
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
mode |
❌ No | enum string | production |
cors |
❌ No | object | None |
authentication |
❌ No | object | None |
Examples
Here's an example of a runtime configured for development hosting.
{
"runtime": {
"host": {
"mode": "development",
"cors": {
"allow-credentials": false,
"origins": ["*"]
},
"authentication": {
"provider": "Simulator"
}
}
}
}
Mode (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host |
mode |
string | ❌ No | "production" |
Defines if the Data API builder engine should run in development or production mode. The default value is production.
Typically, the underlying database errors are exposed in detail by setting the default level of detail for logs to Debug when running in development. In production, the level of detail for logs is set to Error.
Tip
The default log level can be further overriden using dab start --LogLevel <level-of-detail>. For more information, see command-line interface (CLI) reference.
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development"
}
}
}
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
production |
Use when hosting in production on Azure |
development |
Use in development on local machine |
Maximum response size (Runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host |
max-response-size-mb |
integer | ❌ No | 158 |
Sets the maximum size (in megabytes) for any given result. This setting allows users to configure the amount of data that their host platform's memory can handle when streaming data from the underlying data sources.
When users request large result sets, it can strain the database and Data API builder. To address this, max-response-size-mb allows developers to limit the maximum response size, measured in megabytes, as the data streams from the data source. This limit is based on the overall data size, not the number of rows. Since columns can vary in size, some columns (like text, binary, XML, or JSON) can hold up to 2 GB each, making individual rows potentially very large. This setting helps developers protect their endpoints by capping response sizes and preventing system overloads while maintaining flexibility for different data types.
Allowed values
| Value | Result |
|---|---|
null |
Defaults to 158 megabytes if unset or explicitly set to null. |
integer |
Any positive 32-bit integer is supported. |
< 0 |
Not supported. Validation errors occur if set to less than 1 MB. |
Format
{
"runtime": {
"host": {
"max-response-size-mb": <integer; default: 158>
}
}
}
CORS (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host |
cors |
object | ❌ No | None |
Cross-origin resource sharing (CORS) settings for the Data API builder engine host.
Format
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
}
}
}
}
Properties
| Required | Type | |
|---|---|---|
allow-credentials |
❌ No | boolean |
origins |
❌ No | string array |
Allow credentials (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.cors |
allow-credentials |
boolean | ❌ No | False |
If true, sets the Access-Control-Allow-Credentials CORS header.
Note
For more infromation on the Access-Control-Allow-Credentials CORS header, see MDN Web Docs CORS reference.
Format
{
"runtime": {
"host": {
"cors": {
"allow-credentials": <true> (default) | <false>
}
}
}
}
Origins (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.cors |
origins |
string array | ❌ No | None |
Sets an array with a list of allowed origins for CORS. This setting allows the * wildcard for all origins.
Format
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"]
}
}
}
}
Examples
Here's an example of a host that allows CORS without credentials from all origins.
{
"runtime": {
"host": {
"cors": {
"allow-credentials": false,
"origins": ["*"]
}
}
}
}
Authentication (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host |
authentication |
object | ❌ No | None |
Configures authentication for the Data API builder host.
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<string>",
"issuer": "<string>"
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
provider |
❌ No | enum string | StaticWebApps |
jwt |
❌ No | object | None |
Authentication and customer responsibilities
Data API builder is designed to operate within a broader security pipeline, and there are important steps to configure before it processes requests. It’s important to understand that Data API builder does not authenticate the direct caller (such as your web application) but rather the end-user, based on a valid JWT token provided by a trusted identity provider (for example, Entra ID). When a request reaches Data API builder, it assumes the JWT token is valid and checks it against any prerequisites you have configured, such as specific claims. Authorization rules are then applied to determine what the user can access or modify.
Once authorization passes, Data API builder executes the request using the account specified in the connection string. Because this account often requires elevated permissions to handle various user requests, it is essential to minimize its access rights to reduce risk. We recommend securing your architecture by configuring a Private Link between your front-end web application and the API endpoint, and by hardening the machine hosting Data API builder. These measures help ensure your environment remains secure, protecting your data and minimizing vulnerabilities that could be exploited to access, modify, or exfiltrate sensitive information.
Provider (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.authentication |
provider |
string | ❌ No | "StaticWebApps" |
The authentication.provider setting within the host configuration defines the method of authentication used by the Data API builder. It determines how the API validates the identity of users or services attempting to access its resources. This setting allows for flexibility in deployment and integration by supporting various authentication mechanisms tailored to different environments and security requirements.
| Provider | Description |
|---|---|
StaticWebApps |
Instructs Data API builder to look for a set of HTTP headers only present when running within a Static Web Apps environment. |
AppService |
When the runtime is hosted in Azure AppService with AppService Authentication enabled and configured (EasyAuth). |
AzureAd |
Microsoft Entra Identity needs to be configured so that it can authenticate a request sent to Data API builder (the "Server App"). For more information, see Microsoft Entra ID authentication. |
Simulator |
A configurable authentication provider that instructs the Data API builder engine to treat all requests as authenticated. For more information, see local authentication. |
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...
}
}
}
}
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
StaticWebApps |
Azure Static Web Apps |
AppService |
Azure App Service |
AzureAD |
Microsoft Entra ID |
Simulator |
Simulator |
JSON Web Tokens (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.authentication |
jwt |
object | ❌ No | None |
If the authentication provider is set to AzureAD (Microsoft Entra ID), then this section is required to specify the audience and issuers for the JSOn Web Tokens (JWT) token. This data is used to validate the tokens against your Microsoft Entra tenant.
Required if the authentication provider is AzureAD for Microsoft Entra ID. This section must specify the audience and issuer to validate the received JWT token against the intended AzureAD tenant for authentication.
| Setting | Description |
|---|---|
| audience | Identifies the intended recipient of the token; typically the application's identifier registered in Microsoft Entra Identity (or your identity provider), ensuring that the token was indeed issued for your application. |
| issuer | Specifies the issuing authority's URL, which is the token service that issued the JWT. This URL should match the identity provider's issuer URL from which the JWT was obtained, validating the token's origin. |
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
audience |
❌ No | string | None |
issuer |
❌ No | string | None |
Examples
The Data API builder (DAB) offers flexible authentication support, integrating with Microsoft Entra Identity and custom JSON Web Token (JWT) servers. In this image, the JWT Server represents the authentication service that issues JWT tokens to clients upon successful sign-in. The client then passes the token to DAB, which can interrogate its claims and properties.
The following are examples of the host property given various architectural choices you might make in your solution.
Azure Static Web Apps
{
"host": {
"mode": "development",
"cors": {
"origins": ["https://dev.example.com"],
"credentials": true
},
"authentication": {
"provider": "StaticWebApps"
}
}
}
With StaticWebApps, Data API builder expects Azure Static Web Apps to authenticate the request and the X-MS-CLIENT-PRINCIPAL HTTP header is present.
Azure App Service
{
"host": {
"mode": "production",
"cors": {
"origins": [ "https://api.example.com" ],
"credentials": false
},
"authentication": {
"provider": "AppService",
"jwt": {
"audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
"issuer": "https://example-appservice-auth.com"
}
}
}
}
Authentication is delegated to a supported identity provider where access token can be issued. An acquired access token must be included with incoming requests to Data API builder. Data API builder then validates any presented access tokens, ensuring that Data API builder was the intended audience of the token.
Microsoft Entra ID
{
"host": {
"mode": "production",
"cors": {
"origins": [ "https://api.example.com" ],
"credentials": true
},
"authentication": {
"provider": "AzureAD",
"jwt": {
"audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
"issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
}
}
}
}
Simulator (Development-only)
{
"host": {
"mode": "development",
"authentication": {
"provider": "Simulator"
}
}
}
Audience (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.authentication.jwt |
audience |
string | ❌ No | None |
Audience for the JWT token.
Format
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"audience": "<client-id>"
}
}
}
}
}
Issuer (Host runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.host.authentication.jwt |
issuer |
string | ❌ No | None |
Issuer for the JWT token.
Format
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"issuer": "<issuer-url>"
}
}
}
}
}
Pagination (Runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
pagination |
object | ❌ No | None |
Configures pagination limits.
Format
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
max-page-size |
❌ No | integer | 100,000 |
default-page-size |
❌ No | integer | 100 |
Example
{
"runtime": {
"pagination": {
"max-page-size": 100000,
"default-page-size": 1
}
}
}
REST pagination example
In this example, issuing the REST GET https://localhost:5001/api/books would return one record in the value array because the default-page-size was set to 1. If more results exist, Data API builder appends a nextLink in the response. The nextLink contains a $after parameter for retrieving the next page of data.
{
"value": [
{
"id": 1000,
"title": "Prelude to Foundation",
"year": 1988,
"pages": 403,
"series_id": 10000
}
],
"nextLink": "https://localhost:5001/api/books?$after=W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}
Using the nextLink ensures the next set of results is returned, even if the data has changed between queries.
GraphQL pagination example
For GraphQL, use the hasNextPage and endCursor fields for pagination. These are required to fetch the next set of results. Without them, the query is still limited to the default page size.
query {
books {
items {
id,
title,
year,
pages,
series_id
}
hasNextPage
endCursor
}
}
The response includes the hasNextPage and endCursor fields:
{
"data": {
"books": {
"items": [
{
"id": 1000,
"title": "Prelude to Foundation",
"year": 1988,
"pages": 403,
"series_id": 10000
}
],
"hasNextPage": true,
"endCursor": "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}
}
}
To fetch the next page, include the cursor value in the next query:
query {
books(after: "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI==") {
items {
id
title
year
pages
series_id
}
hasNextPage
endCursor
}
}
Using $limit or first to change the page size:
REST and GraphQL both support a $limit or first parameter to adjust the number of results per query. For instance, https://{server}/api/books?$limit=10 limits the result to 10 records, overriding the default-page-size. If $limit exceeds max-page-size, the result is capped at max-page-size.
| First value | Result |
|---|---|
-1 |
Defaults to the current max-page-size setting. |
< max-page-size |
Limits the result to the provided value. |
0 |
Not supported. |
< -1 |
Not supported. |
> max-page-size |
Not supported. |
Maximum page size (Pagination runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.pagination |
max-page-size |
int | ❌ No | 100,000 |
Sets the maximum number of top-level records returned by REST or GraphQL. If a user requests more than max-page-size, the results are capped at max-page-size.
Allowed values
| Value | Result |
|---|---|
-1 |
Defaults to the maximum supported value. |
integer |
Any positive 32-bit integer is supported. |
< -1 |
Not supported. |
0 |
Not supported. |
Format
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>
}
}
}
Default page size (Pagination runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.pagination |
default-page-size |
int | ❌ No | 100 |
Sets the default number of top-level records returned when pagination is enabled but no explicit page size is provided.
Allowed values
| Value | Result |
|---|---|
-1 |
Defaults to the current max-page-size setting. |
integer |
Any positive integer less than the current max-page-size. |
< -1 |
Not supported. |
0 |
Not supported. |
Cache (runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
cache |
object | ❌ No | None |
Enables and configures caching for the entire runtime.
Format
{
"runtime": {
"cache": <object>
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
❌ No | boolean | None |
ttl-seconds |
❌ No | integer | 5 |
Examples
In this example, cache is enabled and the items expire after 30 seconds.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
Enabled (Cache runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.cache |
enabled |
boolean | ❌ No | False |
Enables caching globally for all entities. Defaults to false.
Format
{
"runtime": {
"cache": {
"enabled": <boolean>
}
}
}
Examples
In this example, cache is disabled.
{
"runtime": {
"cache": {
"enabled": false
}
}
}
TTL in seconds (Cache runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.cache |
ttl-seconds |
integer | ❌ No | 5 |
Configures the time-to-live (TTL) value in seconds for cached items. After this time elapses, items are automatically pruned from the cache. The default value is 5 seconds.
Format
{
"runtime": {
"cache": {
"ttl-seconds": <integer>
}
}
}
Examples
In this example, cache is enabled globally and all items expire after 15 seconds.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
Telemetry (runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime |
telemetry |
object | ❌ No | None |
This property configures Application Insights to centralize API logs. Learn more.
Format
{
"runtime": {
"telemetry": {
"application-insights": {
"enabled": <true; default: true> | <false>,
"connection-string": <string>
}
}
}
}
Application Insights (Telemetry runtime)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.telemetry |
application-insights |
object | ✔️ Yes | None |
Enabled (Application Insights telemetry)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.telemetry.application-insights |
enabled |
boolean | ❌ No | True |
Connection string (Application Insights telemetry)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
runtime.telemetry.application-insights |
connection-string |
string | ✔️ Yes | None |
Entities
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
$root |
entities |
object | ✔️ Yes | None |
The entities section serves as the core of the configuration file, establishing a bridge between database objects and their corresponding API endpoints. This section maps database objects to exposed endpoints. This section also includes properties mapping and permission definition. Each exposed entity is defined in a dedicated object. The property name of the object is used as the name of the entity to expose.
This section defines how each entity in the database is represented in the API, including property mappings and permissions. Each entity is encapsulated within its own subsection, with the entity's name acting as a key for reference throughout the configuration.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true; default: true> | <false>,
"path": <string; default: "<entity-name>">,
"methods": <array of strings; default: ["GET", "POST"]>
},
"graphql": {
"enabled": <true; default: true> | <false>,
"type": {
"singular": <string>,
"plural": <string>
},
"operation": <"query" | "mutation"; default: "query">
},
"source": {
"object": <string>,
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>,
"parameters": {
"<parameter-name>": <string | number | boolean>
}
},
"mappings": {
"<database-field-name>": <string>
},
"relationships": {
"<relationship-name>": {
"cardinality": <"one" | "many">,
"target.entity": <string>,
"source.fields": <array of strings>,
"target.fields": <array of strings>,
"linking.object": <string>,
"linking.source.fields": <array of strings>,
"linking.target.fields": <array of strings>
}
},
"permissions": [
{
"role": <"anonymous" | "authenticated" | "custom-role-name">,
"actions": <array of strings>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": {
"database": <string>
}
}
]
}
}
}
Properties
| Required | Type | |
|---|---|---|
source |
✔️ Yes | object |
permissions |
✔️ Yes | array |
rest |
❌ No | object |
graphql |
❌ No | object |
mappings |
❌ No | object |
relationships |
❌ No | object |
cache |
❌ No | object |
Examples
For example, this JSON object instructs Data API builder to expose a GraphQL entity named Author and a REST endpoint reachable via the /Author path. The dbo.authors database table backs the entity and the configuration allows anyone to access the endpoint anonymously.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "*"
}
]
}
]
}
}
}
This example declares the User entity. This name User is used anywhere in the configuration file where entities are referenced. Otherwise the entity name isn't relevant to the endpoints.
{
"entities": {
"Book": {
"rest": {
"enabled": true,
"path": "/books",
"methods": ["GET", "POST", "PUT"]
},
"graphql": {
"enabled": true,
"type": {
"singular": "Book",
"plural": "Books"
},
"operation": "query"
},
"source": {
"object": "BooksTable",
"type": "table",
"key-fields": ["Id"],
"parameters": {}
},
"mappings": {
"id": "Id",
"title": "Title",
"authorId": "AuthorId"
},
"permissions": [
{
"role": "authenticated",
"actions": ["read"],
"fields": {
"include": ["id", "title"],
"exclude": []
},
"policy": {
"database": "@claims.userId eq @item.authorId"
}
},
{
"role": "admin",
"actions": ["create", "read", "update", "delete"],
"fields": {
"include": ["*"],
"exclude": []
},
"policy": {
"database": "@claims.userRoles has 'BookAdmin'"
}
}
]
}
}
}
Source
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
source |
object | ✔️ Yes | None |
The {entity}.source configuration connects the API-exposed entity and its underlying database object. This property specifies the database table, view, or stored procedure that the entity represents, establishing a direct link for data retrieval and manipulation.
For straightforward scenarios, where the entity maps directly to a single database table or collection, the source property needs only the name of that database object. This simplicity facilitates quick setup for common use cases.
Format
{
"entities": {
"<entity-name>": {
"source": {
"object": <string>,
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>,
"parameters": {
"<name>": <string | number | boolean>
}
}
}
}
}
Properties
| Required | Type | |
|---|---|---|
object |
✔️ Yes | string |
type |
✔️ Yes | enum string |
parameters |
❌ No | object |
key-fields |
❌ No | string array |
Examples
This example shows the most straightforward structure to associate an entity with a source table.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
}
}
}
}
Here's an exmaple of a many-to-many relationship.
{
"entities": {
"Todo": {
"type": "stored-procedure",
"source": {
"type": "stored-procedure",
"object": "GetUserTodos"
},
"parameters": {
"UserId": 0,
"Completed": null,
"CategoryName": null
},
"mapping": {
"Id": "todo_id",
"Title": "todo_title",
"Description": "todo_description",
"Completed": "todo_completed"
}
}
}
}
- The
Todoentity backed by a stored procedure. - The
typeproperty within source is set tostored-procedure, indicating the kind of source object the entity is mapped to. - The
objectproperty within source is the name of the stored procedure in the database.
Also in this example, the (optional) mapping property is added to the configuration for the "Todo" entity. It specifies how the fields in the entity (Id, Title, Description, and Completed) map to the corresponding fields in the underlying data source or stored procedure parameters (todo_id, todo_title, todo_description, and todo_completed, respectively). This mapping ensures that the correct data is passed between the entity and the stored procedure during create/update operations.
The previous example would use the following SQL procedure.
CREATE PROCEDURE GetUserTodos
@UserId INT,
@Completed BIT = NULL,
@CategoryName NVARCHAR(100) = NULL
AS
BEGIN
SELECT t.*
FROM Todo t
INNER JOIN users_todos ut ON t.id = ut.todo_id
INNER JOIN Category c ON t.category_id = c.id
WHERE ut.user_id = @UserId
AND ISNULL(@Completed, t.completed)
AND ISNULL(@CategoryName, c.name)
END
@UserId: Mandatory parameter without a default value.@Completed: Optional parameter. If provided, it filters the todos by their completion status.@CategoryName: Optional parameter. If provided, it filters the todos by category name.
Here's an example for updates using a stored procedure.
{
"entities": {
"Todo": {
"type": "stored-procedure",
"source": {
"object": "UpsertTodo"
},
"method": "POST", // Specify the HTTP method as POST
"parameters": {
"Id": 0,
"Title": null,
"Description": null,
"Completed": null
}
}
}
}
This example explicitly sets the HTTP method for interacting with this entity to POST using the method property.
CREATE PROCEDURE UpsertTodo
@Id INT,
@Title NVARCHAR(100),
@Description NVARCHAR(255),
@Completed BIT
AS
BEGIN
SET NOCOUNT ON;
MERGE INTO Todo AS target
USING (VALUES (@Id, @Title, @Description, @Completed)) AS source (Id, Title, Description, Completed)
ON target.Id = source.Id
WHEN MATCHED THEN
UPDATE SET
Title = source.Title,
Description = source.Description,
Completed = source.Completed
WHEN NOT MATCHED THEN
INSERT (Id, Title, Description, Completed)
VALUES (source.Id, source.Title, source.Description, source.Completed);
END;
Object
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.source |
object |
string | ✔️ Yes | None |
Name of the database object to be used.
Examples
In this example, object refers to the dbo.books object in the database.
{
"entities": {
"Book": {
"source": {
"object": "dbo.books",
"type": "table"
}
}
}
}
Type (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.source |
type |
string | ✔️ Yes | None |
The type property identifies the type of database object behind the entity, these include view, table, and stored-procedure. The type property is required and there isn't default value.
Format
{
"entities": {
"<entity-name>": {
"type": <"view" | "stored-procedure" | "table">
}
}
}
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
table |
Represents a table. |
stored-procedure |
Represents a stored procedure. |
view |
Represents a view. |
Examples
In this example, type indicates that this source is a view in the database. This value influences whether other values (ex: key-fields) are required.
{
"entities": {
"Category": {
"source": {
"object": "dbo.vw_category_details",
"type": "view",
"key-fields": [
"category_id"
]
}
}
}
}
Key fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.source |
key-fields |
string array | ❌ No | None |
The {entity}.key-fields setting is necessary for entities backed by views, so Data API builder knows how it can identify and return a single item, if needed. If type is set to view without key-fields, the Data API builder engine refuses to start.
Important
This property is required if the type of object is a view. Also, this property is required is the type of object is a table with no primary key defined.
Format
{
"entities": {
"<entity-name>": {
"source": {
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>
}
}
}
}
Examples
This example uses the dbo.vw_category_details view with category_id indicated as the key field.
{
"entities": {
"Category": {
"source": {
"object": "dbo.vw_category_details",
"type": "view",
"key-fields": [
"category_id"
]
}
}
}
}
Parameters
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.source |
parameters |
object | ❌ No | None |
The {entity}.source.parameters setting is important for entities backed by stored procedures, enabling developers to specify parameters and their default values. Parameters ensure that if certain parameters aren't provided within an HTTP request, the system can fall back to these predefined values.
Important
This property is required if the type of object is a stored-procedure.
Format
{
"entities": {
"<entity-name>": {
"source": {
"type": "stored-procedure",
"parameters": {
"<parameter-name-1>": <string | number | boolean>,
"<parameter-name-2>": <string | number | boolean>,
"<parameter-name-3>": <string | number | boolean>
}
}
}
}
}
Examples
This example invokes the dbo.stp_get_bestselling_books stored procedure passing in these two parameters:
| Value | |
|---|---|
depth |
25 |
list |
contoso-best-sellers |
{
"entities": {
"BestsellingBooks": {
"source": {
"object": "dbo.stp_get_bestselling_books",
"type": "stored-procedure",
"parameters": {
"depth": 25,
"list": "contoso-best-sellers"
}
}
}
}
}
Permissions
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
permissions |
object | ✔️ Yes | None |
This section defines who can access the related entity and what actions are allowed. Permissions are defined in this section in the terms of roles. Actions are defined as typical CRUD operations including: create, read, update, and delete. The section permissions defines who (in terms of roles) can access the related entity and using which actions. Actions are the usual CRUD operations: create, read, update, delete.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"actions": <["create", "read", "update", "delete", "execute", "*"]>
}
]
}
}
}
| Action | Description |
|---|---|
create |
Allows creating a new record in the entity. |
read |
Allows reading or retrieving records from the entity. |
update |
Allows updating existing records in the entity. |
delete |
Allows deleting records from the entity. |
execute |
Allows executing a stored procedure or operation related to the entity. |
* |
Grants all applicable CRUD operations |
Examples
In this example, an anonymous role is defined with access to all possible actions.
{
"entities": {
"Writer": {
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
You can also mix and match string and object array actions.
{
"entities": {
"Reviewer": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read"
},
"create"
]
}
]
}
}
}
Anonymous Role Allow anonymous users to read all fields except the secret-field. The use of "include": ["*"] with "exclude": ["secret-field"] effectively hides secret-field from anonymous users while allowing access to all other fields.
Authenticated Role Allow authenticated users to read and update specific fields, explicitly including id, title, and secret-field, but then excluding secret-field. Demonstrates the explicit inclusion and subsequent exclusion of secret-field, showcasing the precedence of exclude. Since secret-field is both included and excluded, it ends up being inaccessible, which matches the intended rule of exclude taking precedence.
Author Role Authors can do all operations * on all fields without exclusions. The file indicates "include": ["*"] with an empty "exclude": [] array grants access to all fields, as no fields are explicitly excluded.
This configuration represents the default if nothing is specified.
"fields": {
"include": [],
"exclude": []
}
It's effectively identical to:
"fields": {
"include": [ "*" ],
"exclude": []
}
Also consider the following setup:
"fields": {
"include": [],
"exclude": ["*"]
}
The previous configuration effectively specifies that no fields are explicitly included ("include": [] is empty, indicating no fields are allowed) and that all fields are excluded ("exclude": ["*"] uses the wildcard * to indicate all fields).
Practical Use: Such a configuration might seem counterintuitive since it restricts access to all fields. However, it could be utilized in scenarios where a role might perform certain actions - like creating an entity - without accessing any of its data.
The same behavior, but with different syntax, would be:
"fields": {
"include": ["Id", "Title"],
"exclude": ["*"]
}
The previous setup attempts to specify that only the Id and Title fields should be included, while also indicating that all fields should be excluded with the wildcard * in the exclude section. Another way to express the same logic would be:
"fields": {
"include": ["Id", "Title"],
"exclude": ["Id", "Title"]
}
Given the general rule that the exclude list takes precedence over the include list, specifying exclude: ["*"] would typically mean that all fields are excluded, even the fields listed in the include section. Thus, at first glance, this configuration might seem to prevent any fields from being accessible, as the exclusion rule is dominant.
The Reverse: If the intent is to grant, access only to the Id and Title fields, it's clearer and more reliable to specify only those fields in the include section and not use exclude with a wildcard. Alternatively, you could adjust the system's permissions logic to explicitly accommodate such cases, assuming you're in control of its design. For example:
"fields": {
"include": ["Id", "Title"],
"exclude": []
}
Properties
| Required | Type | |
|---|---|---|
role |
✔️ Yes | string |
actions (string-array) or actions (object-array) |
✔️ Yes | object or string array |
Role
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.permissions |
role |
string | ✔️ Yes | None |
String containing the name of the role to which the defined permission applies. The role string contains the name of the role to which the defined permission applies.
Roles set the permissions context in which a request should be executed. For each entity defined in the runtime config, you can define a set of roles and associated permissions that determine how the entity can be accessed in both the REST and GraphQL endpoints. Roles aren't additive. For more information about roles, see authorization.
Data API builder evaluates requests in the context of a single role:
| Role | Description |
|---|---|
anonymous |
No access token is presented |
authenticated |
A valid access token is presented |
<custom-role> |
A valid access token is presented and the X-MS-API-ROLE HTTP header is included specifying a user role that is also included in the access token's roles claim |
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <"anonymous" | "authenticated" | "custom-role">,
"actions": <["create", "read", "update", "delete", "execute", "*"]>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
}
}
]
}
}
}
Examples
This example defines a role named reader with only read permissions on the endpoint.
{
"entities": {
"Book": {
"permissions": [
{
"role": "reader",
"actions": [
"read"
]
}
]
}
}
}
Actions (string-array)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.permissions |
actions |
oneOf [string, array] | ✔️ Yes | None |
An array of string values detailing what operations are allowed for the associated role. For table and view database objects, roles can be configured to use any combination of create, read, update, or delete actions. For stored procedures, roles can only have the execute action. The actions array details what actions are allowed on the associated role. When the entity is either a table or view, roles can be configured with a combination of the actions: create, read, update, delete.
| Action | SQL Operation |
|---|---|
* |
Wildcard, including execute |
create |
Insert one or more rows |
read |
Select one or more rows |
update |
Modify one or more rows |
delete |
Delete one or more rows |
execute |
Runs a stored procedure |
Note
For stored procedures, the wildcard (*) action expands to a list that only includes the execute action. For tables and views, the wildcard action expands to a list that includes create, read, update, and delete actions.
Examples
This example gives create and read permissions to the first role named contributor. The second role named auditor only has delete permissions.
{
"entities": {
"CheckoutLogs": {
"permissions": [
{
"role": "auditor",
"actions": [
"delete"
]
},
{
"role": "contributor",
"actions": [
"read",
"create"
]
}
]
}
}
}
Here's another example.
{
...
"entities": {
"<entity-name>": {
...
"permissions": [
{
"role": "contributor",
"actions": ["read", "create"]
}
]
}
}
}
Actions (object-array)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.permissions |
actions |
string array | ✔️ Yes | None |
An array of string values detailing what operations are allowed for the associated role. For table and view database objects, roles can be configured to use any combination of create, read, update, or delete actions. For stored procedures, roles can only have the execute action.
Note
For stored procedures, the wildcard (*) action expands to a list that only includes the execute action. For tables and views, the wildcard action expands to a list that includes create, read, update, and delete actions.
Format
{
"entities": {
<string>: {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <array of strings>,
"policy": <object>
}
]
}
]
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
action |
✔️ Yes | string | None |
fields |
❌ No | string array | None |
policy |
❌ No | object | None |
Examples
This example grants only read permission to the auditor role. The auditor role can only read specific data using the predicate defined in policy.database. The auditor role is also limited in what fields it can, or can't read using the fields property.
{
"entities": {
"CheckoutLogs": {
"permissions": [
{
"role": "auditor",
"actions": [
{
"action": "read",
"fields": {
"include": ["*"],
"exclude": ["last_updated"]
},
"policy": {
"database": "@item.LogDepth lt 3"
}
}
]
}
]
}
}
}
Action
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.permissions.actions[] |
action |
string | ✔️ Yes | None |
Specifies the specific operation allowed on the database object.
Values
Here's a list of allowed values for this property:
| Tables | Views | Stored Procedures | Description | |
|---|---|---|---|---|
create |
✔️ Yes | ✔️ Yes | ❌ No | Create new items |
read |
✔️ Yes | ✔️ Yes | ❌ No | Point read existing items |
update |
✔️ Yes | ✔️ Yes | ❌ No | Update or replace existing items |
delete |
✔️ Yes | ✔️ Yes | ❌ No | Remove existing items |
execute |
❌ No | ❌ No | ✔️ Yes | Execute programmatic operations |
Format
{
"entities": {
<string>: {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <object>,
"policy": <object>
}
]
}
]
}
}
}
Examples
Here's an example where anonymous users are allowed to execute a specific stored procedure and read a specific table.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read"
}
]
}
]
},
"BestSellingAuthor": {
"source": {
"object": "dbo.stp_get_bestselling_authors",
"type": "stored-procedure",
"parameters": {
"depth": 10
}
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
}
}
Fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.permissions.actions[] |
fields |
object | ❌ No | None |
Granular specifications on which specific fields are permitted access for the database object. Role configuration is an object type with two internal properties, include and exclude. These values support granularly defining which database columns (fields) are permitted access in the section fields.
Format
{
"entities": {
<string>: {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": <object>
}
]
}
]
}
}
}
Examples
In this example, the anonymous role is allowed to read from all fields except id, but can use all fields when creating an item.
{
"entities": {
"Author": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"fields": {
"include": [ "*" ],
"exclude": [ "id" ]
}
},
{ "action": "create" }
]
}
]
}
}
}
Include and exclude work together. The wildcard * in the include section indicates all fields. The fields noted in the exclude section has precedence over fields noted in the include section. The definition translates to include all fields except for the field 'last_updated.'
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ],
// Include All Except Specific Fields
"fields": {
"include": [ "*" ],
"exclude": [ "secret-field" ]
}
},
{
"role": "authenticated",
"actions": [ "read", "update" ],
// Explicit Include and Exclude
"fields": {
"include": [ "id", "title", "secret-field" ],
"exclude": [ "secret-field" ]
}
},
{
"role": "author",
"actions": [ "*" ],
// Include All With No Exclusions (default)
"fields": {
"include": ["*"],
"exclude": []
}
}
]
}
Policy
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.permissions.actions[] |
policy |
object | ❌ No | None |
The policy section, defined per action, defines item-level security rules (database policies) which limit the results returned from a request. The subsection database denotes the database policy expression that is evaluated during request execution.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <object>,
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
database |
✔️ Yes | string | None |
Description
The database policy: an OData-like expression that is translated into a query predicate the database evaluates, including operators like eq, lt, and gt. In order for results to be returned for a request, the request's query predicate resolved from a database policy must evaluate to true when executing against the database.
| Example Item Policy | Predicate |
|---|---|
@item.OwnerId eq 2000 |
WHERE Table.OwnerId = 2000 |
@item.OwnerId gt 2000 |
WHERE Table.OwnerId > 2000 |
@item.OwnerId lt 2000 |
WHERE Table.OwnerId < 2000 |
A
predicateis an expression that evaluates to TRUE or FALSE. Predicates are used in the search condition of WHERE clauses and HAVING clauses, the join conditions of FROM clauses, and other constructs where a Boolean value is required. (Microsoft Learn Docs)
Database policy
Two types of directives can be used to manage database policy when authoring a database policy expression:
| Directive | Description |
|---|---|
@claims |
Access a claim within the validated access token provided in the request |
@item |
Represents a field of the entity for which the database policy is defined |
Note
When Azure Static Web Apps authentication (EasyAuth) is configured, a limited number of claims types are available for use in database policies: identityProvider, userId, userDetails, and userRoles. For more information, see Azure Static Web App's Client principal data documentation.
Here are a few example database policies:
@claims.userId eq @item.OwnerId@claims.userId gt @item.OwnerId@claims.userId lt @item.OwnerId
Data API builder compares the value of the UserId claim to the value of the database field OwnerId. The result payload only includes records that fulfill both the request metadata and the database policy expression.
Limitations
Database policies are supported for tables and views. Stored procedures can't be configured with policies.
Database policies don't prevent requests from executing within the database. This behavior is because they're resolved as predicates in the generated queries that are passed to the database engine.
Database policies are only supported for the actions create, read, update, and delete. Since there's no predicate in a stored procedure call, they can't be appended.
Supported OData-like operators
| Operator | Description | Sample Syntax |
|---|---|---|
and |
Logical AND | "@item.status eq 'active' and @item.age gt 18" |
or |
Logical OR | "@item.region eq 'US' or @item.region eq 'EU'" |
eq |
Equals | "@item.type eq 'employee'" |
gt |
Greater than | "@item.salary gt 50000" |
lt |
Less than | "@item.experience lt 5" |
For more information, see binary operators.
| Operator | Description | Sample Syntax |
|---|---|---|
- |
Negate (numeric) | "@item.balance lt -100" |
not |
Logical negate (NOT) | "not @item.status eq 'inactive'" |
For more information, see unary operators.
Entity field name restrictions
- Rules: Must start with a letter or underscore (
_), followed by up to 127 letters, underscores (_), or digits (0-9). - Impact: Fields not adhering to these rules can't be directly used in database policies.
- Solution: Utilize the
mappingssection to create aliases for fields that don't meet these naming conventions; mappings ensure all fields can be included in policy expressions.
Utilizing mappings for nonconforming fields
If your entity field names don't meet the OData syntax rules or you simply want to alias them for other reasons, you can define aliases in the mappings section of your configuration.
{
"entities": {
"<entity-name>": {
"mappings": {
"<field-1-name>": <string>,
"<field-2-name>": <string>,
"<field-3-name>": <string>
}
}
}
}
In this example, field-1-name is the original database field name that doesn't meet the OData naming conventions. Creating a map to field-1-name and field-1-alias allows this field to be referenced in database policy expressions without issue. This approach not only helps in adhering to the OData naming conventions but also enhances the clarity and accessibility of your data model within both GraphQL and RESTful endpoints.
Examples
Consider an entity named Employee within a Data API configuration that utilizes both claims and item directives. It ensures data access is securely managed based on user roles and entity ownership:
{
"entities": {
"Employee": {
"source": {
"object": "HRUNITS",
"type": "table",
"key-fields": ["employee NUM"],
"parameters": {}
},
"mappings": {
"employee NUM": "EmployeeId",
"employee Name": "EmployeeName",
"department COID": "DepartmentId"
},
"policy": {
"database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
}
}
}
}
Entity Definition: The Employee entity is configured for REST and GraphQL interfaces, indicating its data can be queried or manipulated through these endpoints.
Source Configuration: Identifies the HRUNITS in the database, with employee NUM as the key field.
Mappings: Aliases are used to map employee NUM, employee Name, and department COID to EmployeeId, EmployeeName, and DepartmentId, respectively, simplifying field names and potentially obfuscating sensitive database schema details.
Policy Application: The policy section applies a database policy using an OData-like expression. This policy restricts data access to users with the HR role (@claims.role eq 'HR') or to users whose UserId claim matches EmployeeId - the field alias - in the database (@claims.userId eq @item.EmployeeId). It ensures that employees can only access their own records unless they belong to the HR department. Policies can enforce row-level security based on dynamic conditions.
Database
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.permissions.actions.policy |
database |
object | ✔️ Yes | None |
The policy section, defined per action, defines item-level security rules (database policies) which limit the results returned from a request. The subsection database denotes the database policy expression that is evaluated during request execution.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
This property denotes the database policy expression that is evaluated during request execution. The policy string is an OData expression that is translated into a query predicated evaluated by the database. For example, the policy expression @item.OwnerId eq 2000 is translated to the query predicate WHERE <schema>.<object-name>.OwnerId = 2000.
Note
A predicate is an expression that evalutes to TRUE, FALSE, or UNKNOWN. Predicates are used in:
- The search condition of
WHEREclauses - The search condition of
FROMclauses - The join conditions of
FROMclauses - Other constructs where a boolean value is required.
For more information, see predicates.
In order for results to be returned for a request, the request's query predicate resolved from a database policy must evaluate to true when executing against the database.
Two types of directives can be used to manage the database policy when authoring a database policy expression:
| Description | |
|---|---|
@claims |
Accesses a claim within the validated access token provided in the request |
@item |
Represents a field of the entity for which the database policy is defined |
Note
A limited number of claim types are available for use in database policies when Azure Static Web Apps authentication (EasyAuth) is configured. These claim types include: identityProvider, userId, userDetails, and userRoles. For more information, see Azure Static Web Apps client principal data.
Examples
For example, a basic policy expression can evaluate whether a specific field is true within the table. This example evaluates if the soft_delete field is false.
{
"entities": {
"Manuscripts": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.soft_delete eq false"
}
}
]
}
]
}
}
}
Predicates can also evaluate both claims and item directive types. This example pulls the UserId field from the access token and compares it to the owner_id field in the target database table.
{
"entities": {
"Manuscript": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@claims.userId eq @item.owner_id"
}
}
]
}
]
}
}
}
Limitations
- Database policies are supported for tables and views. Stored procedures can't be configured with policies.
- Database policies can't be used to prevent a request from executing within a database. This limitation is because database policies are resolved as query predicates in the generated database queries. The database engine ultimately evaluates these queries.
- Database policies are only supported for the
actionscreate,read,update, anddelete. - Database policy OData expression syntax only supports these scenarios.
- Binary operators including, but not limited to;
and,or,eq,gt, andlt. For more information, seeBinaryOperatorKind. - Unary operators such as the
-(negate) andnotoperators. For more information, seeUnaryOperatorKind.
- Binary operators including, but not limited to;
- Database policies also have restrictions related to field names.
- Entity field names that start with a letter or underscore, followed by at most 127 letters, underscores, or digits.
- This requirement is per OData specification. For more information, see OData Common Schema Definition Language.
Tip
Fields which do not conform to the mentioned restrictions can't be referenced in database policies. As a workaround, configure the entity with a mappings section to assign conforming aliases to the fields.
GraphQL (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
graphql |
object | ❌ No | None |
This object defines whether GraphQL is enabled and the name[s] used to expose the entity as a GraphQL type. This object is optional and only used if the default name or settings aren't sufficient.
This segment provides for integrating an entity into the GraphQL schema. It allows developers to specify or modify default values for the entity in GraphQL. This setup ensures the schema accurately reflects the intended structure and naming conventions.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <true> (default) | <false>,
"type": {
"singular": <string>,
"plural": <string>
},
"operation": "query" (default) | "mutation"
}
}
}
}
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <boolean>,
"type": <string-or-object>,
"operation": "query" (default) | "mutation"
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
❌ No | boolean | None |
type |
❌ No | string or object | None |
operation |
❌ No | enum string | None |
Examples
These two examples are functionally equivalent.
{
"entities": {
"Author": {
"graphql": true
}
}
}
{
"entities": {
"Author": {
"graphql": {
"enabled": true
}
}
}
}
In this example, the entity defined is Book, indicating we're dealing with a set of data related to books in the database. The configuration for the Book entity within the GraphQL segment offers a clear structure on how it should be represented and interacted with in a GraphQL schema.
Enabled property: The Book entity is made available through GraphQL ("enabled": true), meaning developers and users can query or mutate book data via GraphQL operations.
Type property: The entity is represented with the singular name "Book" and the plural name "Books" in the GraphQL schema. This distinction ensures that when querying a single book or multiple books, the schema offers intuitively named types (Book for a single entry, Books for a list), enhancing the API's usability.
Operation property: The operation is set to "query", indicating that the primary interaction with the Book entity through GraphQL is intended to be querying (retrieving) data rather than mutating (creating, updating, or deleting) it. This setup aligns with typical usage patterns where book data is more frequently read than modified.
{
"entities": {
"Book": {
...
"graphql": {
"enabled": true,
"type": {
"singular": "Book",
"plural": "Books"
},
"operation": "query"
},
...
}
}
}
Type (GraphQL entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.graphql |
type |
oneOf [string, object] | ❌ No | {entity-name} |
This property dictates the naming convention for an entity within the GraphQL schema. It supports both scalar string values and object types. The object value specifies the singular and plural forms. This property provides granular control over the schema's readability and user experience.
Format
{
"entities": {
<entity-name>: {
"graphql": {
"type": <string>
}
}
}
}
{
"entities": {
<entity-name>: {
"graphql": {
"type": {
"singular": <string>,
"plural": <string>
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
singular |
❌ No | string | None |
plural |
❌ No | string | N/A (default: singular) |
Examples
For even greater control over the GraphQL type, you can configure how the singular and plural name is represented independently.
If plural is missing or omitted (like scalar value) Data API builder tries to pluralize the name automatically, following the English rules for pluralization (for example: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)
{
"entities" {
"<entity-name>": {
...
"graphql": {
...
"type": {
"singular": "User",
"plural": "Users"
}
}
}
}
}
A custom entity name can be specified using the type parameter with a string value. In this example, the engine differentiates automatically between the singular and plural variants of this name using common English rules for pluralization.
{
"entities": {
"Author": {
"graphql": {
"type": "bookauthor"
}
}
}
}
If you elect to specify the names explicitly, use the type.singular and type.plural properties. This example explicitly sets both names.
{
"entities": {
"Author": {
"graphql": {
"type": {
"singular": "bookauthor",
"plural": "bookauthors"
}
}
}
}
}
Both examples are functionally equivalent. They both return the same JSON output for a GraphQL query that uses the bookauthors entity name.
{
bookauthors {
items {
first_name
last_name
}
}
}
{
"data": {
"bookauthors": {
"items": [
{
"first_name": "Henry",
"last_name": "Ross"
},
{
"first_name": "Jacob",
"last_name": "Hancock"
},
...
]
}
}
}
Operation (GraphQL entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.graphql |
operation |
enum string | ❌ No | None |
For entities mapped to stored procedures, the operation property designates the GraphQL operation type (query or mutation) where the stored procedure is accessible. This setting allows for logical organization of the schema and adherence to GraphQL best practices, without impacting functionality.
Note
An entity is specified to be a stored procedure by setting the {entity}.type property value to stored-procedure. In the case of a stored procedure, a new GraphQL type executeXXX is automatically created. However, the operation property allows the developer to coerse the location of that type into either the mutation or query parts of the schema. This property allows for schema hygene and there is no functional impact regardless of operation value.
If missing, the operation default is mutation.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"operation": "query" (default) | "mutation"
}
}
}
}
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
query |
The underlying stored procedure is exposed as a query |
mutation |
The underlying stored procedure is exposed as a mutation |
Examples
When operation is mutation, the GraphQL schema would resemble:
type Mutation {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
When operation is query, the GraphQL schema would resemble:
The GraphQL schema would resemble:
type Query {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
Note
The operation property is only about the placement of the operation in the GraphQL schema, it does not change the behavior of the operation.
Enabled (GraphQL entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.graphql |
enabled |
boolean | ❌ No | True |
Enables or disables the GraphQL endpoint. Controls whether an entity is available via GraphQL endpoints. Toggling the enabled property lets developers selectively expose entities from the GraphQL schema.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
}
REST (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
rest |
object | ❌ No | None |
The rest section of the configuration file is dedicated to fine-tuning the RESTful endpoints for each database entity. This customization capability ensures that the exposed REST API matches specific requirements, improving both its utility and integration capabilities. It addresses potential mismatches between default inferred settings and desired endpoint behaviors.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>,
"path": <string; default: "<entity-name>">,
"methods": <array of strings; default: ["GET", "POST"]>
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
✔️ Yes | boolean | True |
path |
❌ No | string | /<entity-name> |
methods |
❌ No | string array | GET |
Examples
These two examples are functionally equivalent.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
],
"rest": true
}
}
}
{
"entities": {
"Author": {
...
"rest": {
"enabled": true
}
}
}
}
Here's another example of a REST configuration for an entity.
{
"entities" {
"User": {
"rest": {
"enabled": true,
"path": "/User"
},
...
}
}
}
Enabled (REST entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.rest |
enabled |
boolean | ❌ No | True |
This property acts as a toggle for the visibility of entities within the REST API. By setting the enabled property to true or false, developers can control access to specific entities, enabling a tailored API surface that aligns with application security and functionality requirements.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>
}
}
}
}
Path (REST entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.rest |
path |
string | ❌ No | None |
The path property specifies the URI segment used to access an entity via the REST API. This customization allows for more descriptive or simplified endpoint paths beyond the default entity name, enhancing API navigability and client-side integration. By default, the path is /<entity-name>.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"path": <string; default: "<entity-name>">
}
}
}
}
Examples
This example exposes the Author entity using the /auth endpoint.
{
"entities": {
"Author": {
"rest": {
"path": "/auth"
}
}
}
}
Methods (REST entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.rest |
methods |
string array | ❌ No | None |
Applicable specifically to stored procedures, the methods property defines which HTTP verbs (for example, GET, POST) the procedure can respond to. Methods enable precise control over how stored procedures are exposed through the REST API, ensuring compatibility with RESTful standards and client expectations. This section underlines the platform's commitment to flexibility and developer control, allowing for precise and intuitive API design tailored to the specific needs of each application.
If omitted or missing, the methods default is POST.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"methods": ["GET" (default), "POST"]
}
}
}
}
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
get |
Exposes HTTP GET requests |
post |
Exposes HTTP POST requests |
Examples
This example instructs the engine that the stp_get_bestselling_authors stored procedure only supports HTTP GET actions.
{
"entities": {
"BestSellingAuthor": {
"source": {
"object": "dbo.stp_get_bestselling_authors",
"type": "stored-procedure",
"parameters": {
"depth": 10
}
},
"rest": {
"path": "/best-selling-authors",
"methods": [ "get" ]
}
}
}
}
Mappings (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
mappings |
object | ❌ No | None |
The mappings section enables configuring aliases, or exposed names, for database object fields. The configured exposed names apply to both the GraphQL and REST endpoints.
Important
For entities with GraphQL enabled, the configured exposed name must meet GraphQL naming requirements. For more information, see GraphQL names specification.
Format
{
"entities": {
"<entity-name>": {
"mappings": {
"<field-1-name>": "<field-1-alias>",
"<field-2-name>": "<field-2-alias>",
"<field-3-name>": "<field-3-alias>"
}
}
}
}
Examples
In this example, the sku_title field from the database object dbo.magazines is exposed using the name title. Similarly, the sku_status field is exposed as status in both REST and GraphQL endpoints.
{
"entities": {
"Magazine": {
...
"mappings": {
"sku_title": "title",
"sku_status": "status"
}
}
}
}
Here's another example of mappings.
{
"entities": {
"Book": {
...
"mappings": {
"id": "BookID",
"title": "BookTitle",
"author": "AuthorName"
}
}
}
}
Mappings: The mappings object links the database fields (BookID, BookTitle, AuthorName) to more intuitive or standardized names (id, title, author) that is used externally. This aliasing serves several purposes:
Clarity and Consistency: It allows for the use of clear and consistent naming across the API, regardless of the underlying database schema. For instance,
BookIDin the database is represented asidin the API, making it more intuitive for developers interacting with the endpoint.GraphQL Compliance: By providing a mechanism to alias field names, it ensures that the names exposed through the GraphQL interface comply with GraphQL naming requirements. Attention to names is important because GraphQL has strict rules about names (for example, no spaces, must start with a letter or underscore, etc.). For example, if a database field name doesn't meet these criteria, it can be aliased to a compliant name through mappings.
Flexibility: This aliasing adds a layer of abstraction between the database schema and the API, allowing for changes in one without necessitating changes in the other. For instance, a field name change in the database doesn't require an update to the API documentation or client-side code if the mapping remains consistent.
Field Name Obfuscation: Mapping allows for the obfuscation of field names, which can help prevent unauthorized users from inferring sensitive information about the database schema or the nature of the data stored.
Protecting Proprietary Information: By renaming fields, you can also protect proprietary names or business logic that might be hinted at through the database's original field names.
Relationships (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity} |
relationships |
object | ❌ No | None |
This section maps includes a set of relationship definitions that map how entities are related to other exposed entities. These relationship definitions can also optionally include details on the underlying database objects used to support and enforce the relationships. Objects defined in this section are exposed as GraphQL fields in the related entity. For more information, see Data API builder relationships breakdown.
Note
Relationships are only relevant to GraphQL queries. REST endpoints access only one entity at a time and can't return nested types.
The relationships section outlines how entities interact within the Data API builder, detailing associations and potential database support for these relationships. The relationship-name property for each relationship is both required and must be unique across all relationships for a given entity. Custom names ensure clear, identifiable connections and maintain the integrity of the GraphQL schema generated from these configurations.
| Relationship | Cardinality | Example |
|---|---|---|
| one-to-many | many |
One category entity can relate to many todo entities |
| many-to-one | one |
Many todo entities can relate to one category entity |
| many-to-many | many |
One todo entity can relate to many user entities, and one user entity can relate to many todo entities |
Format
{
"entities": {
"<entity-name>": {
"relationships": {
"<relationship-name>": {
"cardinality": "one" | "many",
"target.entity": "<string>",
"source.fields": ["<string>"],
"target.fields": ["<string>"],
"linking.object": "<string>",
"linking.source.fields": ["<string>"],
"linking.target.fields": ["<string>"]
}
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
cardinality |
✔️ Yes | enum string | None |
target.entity |
✔️ Yes | string | None |
source.fields |
❌ No | string array | None |
target.fields |
❌ No | string array | None |
linking.<object-or-entity> |
❌ No | string | None |
linking.source.fields |
❌ No | string array | None |
linking.target.fields |
❌ No | string array | None |
Examples
When considering relationships, it's best to compare the differences between one-to-many, many-to-one, and many-to-many relationships.
One-to-many
First, let's consider an example of a relationship with the exposed Category entity has a one-to-many relationship with the Book entity. Here, the cardinality is set to many. Each Category can have multiple related Book entities while each Book entity is only associated with a single Category entity.
{
"entities": {
"Book": {
...
},
"Category": {
"relationships": {
"category_books": {
"cardinality": "many",
"target.entity": "Book",
"source.fields": [ "id" ],
"target.fields": [ "category_id" ]
}
}
}
}
}
In this example, the source.fields list specifies the id field of the source entity (Category). This field is used to connect to the related item in the target entity. Conversely, the target.fields list specifies the category_id field of the target entity (Book). This field is used to connect to the related item in the source entity.
With this relationship defined, the resulting exposed GraphQL schema should resemble this example.
type Category
{
id: Int!
...
books: [BookConnection]!
}
Many-to-one
Next, consider many-to-one which sets the cardinality to one. The exposed Book entity can have a single related Category entity. The Category entity can have multiple related Book entities.
{
"entities": {
"Book": {
"relationships": {
"books_category": {
"cardinality": "one",
"target.entity": "Category",
"source.fields": [ "category_id" ],
"target.fields": [ "id" ]
}
},
"Category": {
...
}
}
}
}
Here, the source.fields list specifies that the category_id field of the source entity (Book) references the id field of the related target entity (Category). Inversely, the target.fields list specifies the inverse relationship. With this relationship, the resulting GraphQL schema now includes a mapping back from Books to Categories.
type Book
{
id: Int!
...
category: Category
}
Many-to-many
Finally, a many-to-many relationship is defined with a cardinality of many and more metadata to define which database objects are used to create the relationship in the backing database. Here, the Book entity can have multiple Author entities and conversely the Author entity can have multiple Book entities.
{
"entities": {
"Book": {
"relationships": {
...,
"books_authors": {
"cardinality": "many",
"target.entity": "Author",
"source.fields": [ "id" ],
"target.fields": [ "id" ],
"linking.object": "dbo.books_authors",
"linking.source.fields": [ "book_id" ],
"linking.target.fields": [ "author_id" ]
}
},
"Category": {
...
},
"Author": {
...
}
}
}
}
In this example, the source.fields and target.fields both indicate that the relationship table uses the primary identifier (id) of both the source (Book) and target (Author) entities. The linking.object field specifies that the relationship is defined in the dbo.books_authors database object. Further, linking.source.fields specifies that the book_id field of the linking object references the id field of the Book entity and linking.target.fields specifies that the author_id field of the linking object references the id field of the Author entity.
This example can be described using a GraphQL schema similar to this example.
type Book
{
id: Int!
...
authors: [AuthorConnection]!
}
type Author
{
id: Int!
...
books: [BookConnection]!
}
Cardinality
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
cardinality |
string | ✔️ Yes | None |
Specifies if the current source entity is related to only a single instance of the target entity or multiple.
Values
Here's a list of allowed values for this property:
| Description | |
|---|---|
one |
The source only relates to one record from the target |
many |
The source can relate to zero-to-many records from the target |
Target entity
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
target.entity |
string | ✔️ Yes | None |
The name of the entity defined elsewhere in the configuration that is the target of the relationship.
Source fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
source.fields |
array | ❌ No | None |
An optional parameter to define the field used for mapping in the source entity used to connect to the related item in the target entity.
Tip
This field isn't required if there's a foreign key restraint on the database between the two database objects that can be used to infer the relationship automatically.
Target fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
target.fields |
array | ❌ No | None |
An optional parameter to define the field used for mapping in the target entity used to connect to the related item in the source entity.
Tip
This field isn't required if there's a foreign key restraint on the database between the two database objects that can be used to infer the relationship automatically.
Linking object or entity
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
linking.object |
string | ❌ No | None |
For many-to-many relationships, the name of the database object or entity that contains the data necessary to define a relationship between two other entities.
Linking source fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
linking.source.fields |
array | ❌ No | None |
The name of the database object or entity field that is related to the source entity.
Linking target fields
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.relationships |
linking.target.fields |
array | ❌ No | None |
The name of the database object or entity field that is related to the target entity.
Cache (entities)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.cache |
enabled |
boolean | ❌ No | False |
Enables and configures caching for the entity.
Format
You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:
```json
{
"entities": {
"<entity-name>": {
"cache": {
"enabled": <true> (default) | <false>,
"ttl-seconds": <integer; default: 5>
}
}
}
}
Properties
| Property | Required | Type | Default |
|---|---|---|---|
enabled |
❌ No | boolean | False |
ttl-seconds |
❌ No | integer | 5 |
Examples
In this example, cache is enabled and the items expire after 30 seconds.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
}
Enabled (Cache entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.{entity}.cache |
enabled |
boolean | ❌ No | False |
Enables caching for the entity.
Database Object Support
| Object type | Cache support |
|---|---|
| Table | ✅ Yes |
| View | ✅ Yes |
| Stored Procedure | ✖️ No |
| Container | ✖️ No |
HTTP Header Support
| Request Header | Cache support |
|---|---|
no-cache |
✖️ No |
no-store |
✖️ No |
max-age |
✖️ No |
public |
✖️ No |
private |
✖️ No |
etag |
✖️ No |
Format
{
"entities": {
"<entity-name>": {
"cache": {
"enabled": <boolean> (default: false)
}
}
}
}
Examples
In this example, cache is disabled.
{
"entities": {
"Author": {
"cache": {
"enabled": false
}
}
}
}
TTL in seconds (Cache entity)
| Parent | Property | Type | Required | Default |
|---|---|---|---|---|
entities.cache |
ttl-seconds |
integer | ❌ No | 5 |
Configures the time-to-live (TTL) value in seconds for cached items. After this time elapses, items are automatically pruned from the cache. The default value is 5 seconds.
Format
{
"entities": {
"<entity-name>": {
"cache": {
"ttl-seconds": <integer; inherited>
}
}
}
}
Examples
In this example, cache is enabled and the items expire after 15 seconds. When omitted, this setting inherits the global setting or default.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
}