references/config-schema.md — Data Room Toolkit

# Configuration schema

Configuration is a JSON object. It must never contain credentials.

## Fields

| Field | Type | Meaning |
| --- | --- | --- |
| `drive_id` | string | Target document-library drive. Takes precedence over `site_id` for resolution. |
| `site_id` | string | Site identifier used to resolve the default drive when `drive_id` is absent. |
| `root_path` | string | Optional library-relative folder; "/" or empty means the whole library. |
| `request_timeout_seconds` | number | Per-request timeout. Must be positive. |
| `throttle_seconds` | number | Delay between ordinary requests. Must be zero or positive. |
| `max_retries` | integer | Retry count after the first attempt for 429 and 5xx responses; writes retry only on 429 or on 503 with `Retry-After`, except the final replacement range is never retried. Must be zero or positive. |
| `upload_chunk_bytes` | integer | Chunk size for upload sessions. Default 5242880 (5 MiB); positive integer multiple of 327680 (320 KiB), strictly below 62914560 (60 MiB). Invalid configuration or CLI values are refused before any request. |
| `small_file_threshold_bytes` | integer | Creates at or below this size use direct PUT; every replacement uses an upload session. Must be positive. |

Unknown fields are ignored by the current command-line tools. Credentials,
hostnames, local source paths, destination paths, keyword lists, and audit-log
paths should remain explicit command choices rather than shared configuration.

Root and remote paths are validated before requests: dot or empty segments,
absolute or drive-qualified forms, backslashes, control characters and
percent-encoded traversal (decoded once and rechecked) are rejected. History
paths are relative to `root_path`; requests resolve beneath that root.

The selected mirror destination must already exist. The mirror refuses a
missing destination before any write, never inspects or creates ancestors
above it, and creates only approved folders beneath it.

## Precedence

For every supported field, precedence is:

1. A command-line flag supplied for that field
2. The configuration file
3. The command's built-in default

The file path comes from `--config PATH`, then
`SHAREPOINT_DATAROOM_CONFIG`. An explicitly supplied flag always wins over the
environment-selected file field by field. At least one of `drive_id` or
`site_id` must resolve from flags and configuration together.

## Worked examples

Direct drive target:

```json
{
  "drive_id": "DRIVE_ID_FROM_ADMIN",
  "root_path": "Shared Records",
  "request_timeout_seconds": 60,
  "throttle_seconds": 0.5,
  "max_retries": 4,
  "upload_chunk_bytes": 5242880,
  "small_file_threshold_bytes": 4194304
}
```

Site fallback:

```json
{
  "site_id": "SITE_ID_FROM_ADMIN",
  "root_path": "Review"
}
```

This command replaces only `root_path`; other values still come from the file:

```bash
python3 scripts/dataroom_search.py --config dataroom.config.json --root-path "Current" --json
```

## Site resolution

When no drive ID is available, the client sends one Graph GET request for the
site's default drive and uses the returned drive ID for the remaining calls.
The endpoint behavior and whether a non-default document library is required
must be verified against Microsoft documentation. Supply `drive_id` when the
target is not the site's default library.

root_path normalizes exactly one leading and one trailing slash before
validation. Repeated slashes, empty/dot segments, backslashes and encoded
traversal remain invalid. Other relative paths are not normalized.

Upload sessions default to 5 MiB (5,242,880 bytes = 16 x 327,680). Configuration and `--chunk-size` must be positive integer multiples of 320 KiB and strictly less than 60 MiB per request; invalid sizes are refused before authentication or any request. The final range may be shorter. See [Microsoft upload-session requirements](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession?view=graph-rest-1.0).

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing