Turn a DBML schema and a YAML mapping into a fail-closed script that provisions SharePoint Online lists from the browser console.

dbml-sharepoint reads a DBML schema, a YAML mapping and a release file, and builds an idempotent, fail-closed, browser-console deploy.js.txt. That script provisions SharePoint Online lists and document libraries, with their columns, lookups, views, indexes, permission levels, groups and ACLs.

It is for site owners and M365 operators who need real lists on a site they own, and have no tenant admin rights, no premium licence, and nothing installed on the target. If you can open the site and press F12, you can deploy.

At a glance

schema.dbml + mapping.yaml + release.yaml
        |
        v   dbml-sharepoint build
+---------------------------------------------------+
| deploy-manifest.md   <- read first                |
| assess.js.txt        <- probe the site, read-only |
| assess-manifest.md   <- how to read the verdict   |
| deploy.js.txt        <- paste to provision        |
| verify.js.txt        <- check the clock rules     |
| demo-data.js.txt     <- demonstrate (--seed)      |
| rollback.js.txt      <- escape a failed first run |
| reporting/           <- Power BI and SQL          |
| index.md             <- what is in the bundle     |
| checksums.txt        <- SHA-256 of every file     |
+---------------------------------------------------+
        |
        v   paste into the site's browser console (F12)
   SharePoint Online lists, ready to use

verify.js.txt is emitted only when the pack reads a clock (a today or now save rule, a today view window, or a [today] default). demo-data.js.txt is emitted only with --seed. Everything else comes with every build.

Why

• Design as code. Your list schema lives in DBML: reviewable, diffable, renderable as an ERD on dbdiagram.io, with indexes declared beside their tables. Deployment and presentation mapping (prefixes, templates, versioning, views, formatting, ACLs) lives in YAML next to it.
• Deploy with nothing but a browser. The generated script runs in the site's own console under your own login, calling SharePoint REST and CSOM endpoints. No PnP, no CSOM installs, no app registrations, no Graph consent, no stored credentials. See the security model and, for an honest look at what PnP, site scripts and Graph offer that this tool does not, why not PnP, site scripts, or Graph?
• Fail closed, rerun safely. Every write is preceded by read-only preflights. The wrong site aborts. An existing list needs the exact provenance marker and matching immutable shape, and an existing field needs matching immutable shape. Mutable drift is narrowly reconciled and read back. Reruns skip work the script can verify is already correct, which it decides by reading the live site rather than by comparing release tags. See the safety model.
• Real column support. Text, note, choice (with defaults), person, date, number, boolean, hyperlink, same-site lookups (including deferred circular and self-lookups), calculated columns (formulas in the mapping), indexes, and unique constraints.
• Security is part of the schema. Custom permission levels, site groups (with automated owner assignment via CSOM and optional run-scoped operator self-enrolment), and broken-inheritance list ACLs with an exact allowlist reconciliation mode (reconcile: exact) that removes undeclared direct grants.
• The whole lifecycle ships in the bundle. A read-only site assessment before you deploy, optional demo data to demonstrate with, a retention-aware rollback to tear down, and a reporting pack for Power BI and SQL.

Install

uv tool install dbml-sharepoint
# or: pip install dbml-sharepoint
# or, without installing anything: uvx dbml-sharepoint

Check it with dbml-sharepoint version. The solution templates are part of the package, so an install is all you need to use them, no clone required.

This page documents main, which can be ahead of the latest release on PyPI. If the released version refuses a flag or a mapping key you see here, check the changelog or take main directly:

uv tool install git+https://github.com/firmfooting/dbml-sharepoint

Quickstart

Run it with no arguments and pick one of the shipped templates:

dbml-sharepoint

The wizard copies the template you choose into a project directory of your own, sets your site URL, time zone and (optionally) a list-name prefix, and offers to build it. It changes identity only. The schema and the mapping structure are the tested artifacts and are copied as they ship. Everything it does is also available as flags. It prompts only at a terminal, and prints help in CI or a pipe.

Or drive it with flags

A complete worked example lives in examples/project-tracker:

dbml-sharepoint build \
  --schema examples/project-tracker/schema.dbml \
  --mapping examples/project-tracker/mapping.yaml \
  --release examples/project-tracker/release.yaml \
  --site-url https://yourtenant.sharepoint.com/sites/your-site \
  --time-zone Region/City \
  --site-role default \
  --out ./build

Then:

1. Read build/deploy-manifest.md. It opens with step-by-step run instructions and must show 0 validation errors. (build/index.md lists every artifact, including the reporting/ queries.)
2. Open https://yourtenant.sharepoint.com/sites/your-site/_layouts/15/settings.aspx signed in as a Site Owner. It is a classic page, because the script's wrong-site guard needs _spPageContextInfo.
3. F12 -> Console -> paste the whole of build/deploy.js.txt -> Enter.
4. Watch the [SP-DEPLOY] lines. Success ends with a summary and errors: [].
5. If the build emitted build/verify.js.txt, paste it next, on the same site, and read its verdict.

The pasteable scripts end in .js.txt, not .js. They exist to be opened and copied, never executed from disk, and on Windows a .js file is bound to Windows Script Host, so double-clicking one runs a provisioning script outside the browser. .js.txt opens in a text editor everywhere. Editors that colour by extension will treat them as plain text; rename a copy if you want highlighting while reviewing.

The three inputs

See examples/project-tracker/README.md for a guided tour of all three.

Documentation

The full documentation is at firmfooting.github.io/dbml-sharepoint.

Limitations

• SharePoint Online only.
• Same-site lookups only. A relationship into a list on another site needs the mapping's cross_site_reference_columns pattern (a Choice and URL pair) instead of a real Lookup.
• Clean first provision + same-release resume. A schema upgrade whose immutable shapes changed (field types, lookup targets, list templates) fails closed for explicit migration rather than guessing.
• Calculated columns cannot reference Lookup, Person, multi-line text, rich text, hyperlink or multi-value Choice columns, or [Today]. These are SharePoint's rules. The build refuses each of them, naming the column and the operand, before any script is emitted. See the DBML reference.
• The browser-paste model means an interactive operator. That is the point (no stored credentials, no app principal), but it is not unattended CI.

Contributing

Read CONTRIBUTING.md. It covers setup, the gates every change must pass, and how pull requests are titled and merged. The module layout and conventions are on the docs site under Architecture and Development. Report security issues as described in SECURITY.md.

Licence

MIT: see LICENSE.

_{Part of firmfooting: safe, plain tooling for M365 and SharePoint operators. Not affiliated with or endorsed by Microsoft.}