Summary

Allow a single DAB instance to interact with multiple backend data sources.

Motivation

This design enables DAB to address more sophisticated customers.

Old behavior

Currently, DAB supports only a single data source and a single dab-config.json file.

Barriers to multiple data sources:

1. The data-source property in the config is of type object, not array.
2. The data-source property in the config applies to every entity.

New behavior

Support the use of multiple dab-config.json files, each corresponding to a different data-source, to merge at runtime.

⭐ When DAB starts, the GLOBAL and CHILD files will be merged.

Design goals:

1. A single dab-config.json file must always be viable in DAB.
2. We will not impose arbitrary limits on data-source or entities at this time.
3. Developers must easily understand which file has an error.
4. entity names across all files must be unique to support future features.

Sample global file

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v0.7.6/dab.draft.schema.json",
  "data-source-files": [
     "dab-config.mssql-hr.json",
     "dab-config.cosmosdb-sales.json",
     "dab-config.mysql-inventory.json",
     "dab-config.postgres-shipping.json",
   ],
  ...
}

Global file characteristics

1. The global file must have runtime properties.
2. The global file's data-source property is optional.
3. The global file's data-source-files property is optional.
4. Paths in data-source-files may include Unicode characters.

New data-source-files property in JSON schema.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "data-source-files": { // new property
      "type": "array",
      "description": "Child file paths",
      "items": {
        "type": "string"
      },
      "default": []
  }
}

This new property, of type string[], is optional. If the data-source-files property is [] or omitted, the data-source property is required. Otherwise, the data-source property is optional.

Path translation

When filled, the data-source-files property contains paths to child files. These paths can include dots . and slashes / & \, indicating the location of the child file relative to the global config file.

If the global config file is at c:\web\api\dab-config.json, then:

Child file characteristics

1. A child file must have a data source defined.
2. A child file may define data-source-files, which can be thought of as "grandchild" files.
3. A child file may be used as a global file if it has runtime properties set.
4. If a child file has runtime properties, they will be ignored; the global file is always used.
5. A child file can be named anything and be located in any accessible folder relative to the global file.