The Obsidian gateway to mdbase v0.3 collections and mdbase Connect.
The plugin is deliberately type-first. Its main workspace provides:
- a searchable type workbench with guided and YAML editing;
- local collection initialization;
- read-only support for mdbase v0.2.x and reviewed migration to v0.3.x;
- hosted collection enrollment, sync preview, mirroring, progress, and conflict handling;
- collection validation with bounded issue rendering for large vaults.
It works through Obsidian's Vault, HTTP, IndexedDB, and SecretStorage APIs. The production bundle has no Node filesystem dependency and is checked against a mobile bundle budget.
Canonical view files remain ordinary v0.3 records in this adapter. When a
collection materializes _types/view.md (normally referring to
schemas/v0.3/view.schema.json), the plugin validates their nested shared
query and named-view frontmatter like any other typed record. This plugin does
not execute named views or advertise the optional view_records feature; it
leaves execution and presentation to query-capable companion tools.
On first open, the workspace asks one question: where does the collection live? Start a collection makes this vault its source. Copy from Connect makes this vault a synced copy of a hosted collection. A local collection can later be uploaded to Connect from the Sync tab.
Start a collection creates a canonical v0.3 mdbase.yaml and _types/
directory. The vault is authoritative and remains an ordinary collection of
files. First run offers published mdbase-contracts
packs with reviewed, digest-verified installation and a portable lockfile;
it does not invent a starter type. Local starter customizations are preserved.
Pack upgrades and custom mappings remain in mdbase editor.
Copy from Connect enrolls the vault through mdbase Connect. The
portable directory-mirror engine syncs hosted resources, records, and opt-in
collection files into the vault. A mirror role marker is stored below
.mdbase/; credentials are stored only in Obsidian SecretStorage.
The plugin refuses to enroll a directory that contains local collection authority metadata. Sync is preflighted, protected by an in-process lease, and conservative around conflicts.
Sync now plans the sync and applies it straight away when every change is routine: note creates, updates and renames. A plan stops for review when it contains the first sync, a rebuild, deletions, conflicts, attachment uploads, blocking issues, more than 200 changes, or more than 25 MiB. The review is an exact transfer ledger grouped by downloads, uploads, and items needing attention, with the reasons it was held. If the hosted head or local changes move after review, the plugin stops and asks for a fresh review.
Sync automatically (off by default, in settings) applies routine plans in the background after local edits settle and when the periodic status check finds changes. Plans that need review are never applied in the background; the status bar shows "Review N changes" and the Sync tab carries a badge. Sync can be stopped safely after the current request without losing its durable checkpoint, and path collisions never overwrite local files silently. Disabling the plugin cancels sync/enrollment/adoption and fences subsequent mirror content writes; an already-issued Vault write or HTTP request may still finish.
Markdown always syncs. Binary files are an explicit per-device choice in settings, grouped as images, audio, video, PDFs, and other files, with collection-relative folder exclusions. Hidden, reserved, Markdown, and non-portable file paths are never materialized. Downloads and uploads are digest-verified; writable uploads are staged in a chunked, content-addressed IndexedDB cache so an interrupted sync can resume safely. Binary sync and adoption currently enforce a 32 MiB per-file limit on desktop and mobile: Obsidian's Vault APIs require whole-file buffers, so chunked network transfer does not imply bounded-memory streaming. Oversized files fail explicitly; exclude their folder from file sync before retrying. Binary creates, updates, moves, deletes, and conflicts appear as files—not Markdown—in the preflight ledger. Local collection adoption uses the same policy and stages exact bytes for both warm and fenced snapshots.
The status bar reports whether the mirror is synced, has changes waiting, is transferring a named file, is paused, has changes held for review, or needs attention. Sync history is one device-local log of transfers and events (reconnects, conflict decisions, pauses, failures); events that need acknowledgement stay pinned until dismissed. The Sync tab shows byte progress for large files, and translates expired approval, offline service, stale review, cancellation, and durable recovery into explicit next actions. Conflict review provides a bounded Markdown diff or binary metadata and a local image preview, with Keep local, Use hosted, and collision-safe Keep both decisions.
Connection details, reconnect, attachments, excluded folders and disconnect live in the plugin's settings tab.
Disconnecting is explicit: retain the vault as a local unsynced copy, or remove only files that still exactly match the last durable checkpoint. Locally changed files are always preserved. The plugin removes the connection before it starts file deletion, so failed settings persistence cannot turn local cleanup into remote deletions.
Commands: Open workspace, Create type definition, Edit type definition (the current note's type, or a picker), Create note from type, Validate current note, Validate collection, and, for a synced vault, Sync now and Show sync history for current note. Initialize collection, Cancel current sync, Resolve sync conflicts and Reconnect collection appear only when they apply.
Open mdbase: Open workspace and choose Types.
- Design mode edits identity, membership, placement, and recursive field schemas—including nested objects, lists, lists of objects, enums, and links.
- The application compatibility section discovers local record contracts under
_contracts/, lets you map contract fields to type fields, and edits binding settings from their JSON Schema. - YAML mode exposes the canonical type definition.
- Unknown v0.3 schema and extension data is preserved by guided edits.
- Drafts survive plugin reloads and Obsidian restarts; stale source revisions are blocked, and high-impact schema changes require an explicit review.
- Dirty changes and validation failures are shown before save.
- Stale drafts can be compared, exported or explicitly discarded without losing newer edits.
New noteopens one validated form with a location preview and retained input.- Validation quick fixes target exact nested properties, preserve sibling data, and use Obsidian's atomic file processing API. Ambiguous legacy nested paths are not offered automatic fixes.
- v0.2 definitions are browsable but read-only until migration.
Validation reports coverage and freshness, not merely an empty issue list. Collection scans show progress and can be stopped without claiming completion. Transfer review searches and paginates the full plan; filters never narrow the approved transfer scope. A bad file no longer pauses the entire sync: independent files transfer while blocked files and related moves remain untouched for retry. Unscoped inspection failures and competing-write protections still stop unsafe operations. See UX acceptance for the live Obsidian harness, verification evidence and implementation limits.
On mobile, the type list and editor use separate navigation states with touch-sized actions instead of a compressed desktop split view.
The migration review shows the source and target versions, every planned write, warnings, lossy diagnostics, record-equivalence results, and the recovery location.
Migration:
- verifies that source files have not changed since analysis;
- requires explicit consent for any lossy conversion;
- writes backups and a recovery manifest below
.mdbase/migrations/; - writes configuration and type definitions sequentially and rolls back on failure;
- verifies the result;
- never rewrites records.
Existing v0.3 collections are not offered migration.
The plugin also hosts local application interoperability for companion plugins:
const host = app.plugins.getPlugin("mdbase-obsidian");
const client = host?.api.interop.connect(yourPlugin);Enable Allow local application interoperability in mdbase settings first. The grant is deliberately off by default and is independent of contract compatibility: matching schemas do not authorize an application.
The bridge verifies each caller from Obsidian's active plugin registry. Event sources publish CloudEvents 1.0 envelopes to every compatible subscriber. Actions resolve to exactly one compatible provider; zero providers and ambiguous providers fail explicitly. Every delivered event and action outcome records the exact contract version and digest plus application and implementation identity.
The bridge is cooperative, same-process transport for Obsidian plugins. It does not claim to be a durable runtime: workflows, scheduling, retries, recovery, and runtime-policy admission belong to a Runtime 0.2 host such as Connect. It does not claim durable delivery or cross-device execution.
npm install
npm test
npm run buildStability regression tests cover interrupted adoption cleanup, unload during
binary materialization, nested quick fixes, binary size limits, and production
IndexedDB adapters using fake-indexeddb (including aborted transactions and
mirror restart recovery). These are not a substitute for real Obsidian/mobile
suspension, quota, and restart acceptance testing.
Additional gates:
npm run check:mobile
npm run profile:testvault
npm run build:test
npm run build:test:stagingbuild:test copies the production-default build to configured test vaults.
build:test:staging builds the enrollment UI with
https://connect-staging.mdbase.dev as its default and copies that exact bundle.
profile:testvault scans the registered Obsidian vault named test without
writing it and enforces checked-in schema, migration-analysis, validation, and
issue-render budgets. Set OBSIDIAN_TEST_VAULT to profile another registered
disposable vault with the exact installed bundle.
The Connect protocol and sync SDKs are pinned to 0.1.0-beta.120, and mdbase
interop is pinned to 0.1.0-rc.2. npm ci applies a version-specific sync SDK
reliability patch (see patches/README.md). Update
package.json, regenerate package-lock.json, rebase or remove the patch, and
rerun the binary round-trip, lossless (npm run test:lossless, part of
npm test) and mobile gates when advancing them. See
SDK consumer qualification.
- Authoring target: mdbase v0.3.x
- Read and migration input: mdbase v0.2.x
- Obsidian minimum version: 1.11.4
- Desktop and mobile supported
The plugin is not a general record editor, query dashboard, or Connect server administration client.