Skip to content

docs: discover Obsidian Bases through record contracts #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
callumalpass wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: discover Obsidian Bases through record contracts #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

All notable changes to this specification and conformance suite are documented here.

## Unreleased

### Changed

- Obsidian Bases discovery uses records whose type implements `obsidian.base`.
The catalog pack opts into the `base` record extension through a collection-setup
`contains` requirement and `set_add` provision; the legacy include-list route is
superseded.

## 0.3.0-rc.5 (draft, untagged)

The fifth release candidate specifies the data semantics that let several
Expand Down
83 changes: 40 additions & 43 deletions adapters/obsidian-bases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
## Purpose

This companion document defines how an mdbase collection provider exposes
Obsidian `.base` files as saved-view sources. It builds on the saved-view model
in [Querying](../11-querying.md) and the saved-view operations in
Obsidian Bases document records as saved-view sources. It builds on the saved-view
model in [Querying](../11-querying.md) and the view operations in
[Operations](../12-operations.md). Implementations that do not advertise the
`obsidian_bases_views` optional feature ignore `.base` files and the
`x-obsidian` configuration section.
`obsidian_bases_views` optional feature can still store and edit these records;
they need not discover or execute them as views.

## Bases as records

Expand All @@ -21,7 +21,7 @@ its type implements `mdbase.view`:
kind: mdbase.type
name: obsidian_base
version: 1
match: { path_glob: 'TaskNotes/Views/**/*.base' }
match: { path_glob: '**/*.base' }
implements:
- contract: obsidian.base
version: 1.0.0
Expand All @@ -37,46 +37,43 @@ grants. Because Obsidian owns the format, writers SHOULD replace a Base with a
whole-document `update` so comments and layout survive; structured patches
remain valid but re-emit the YAML.

The type's path match replaces `x-obsidian.bases.include`, and the record
operations replace the saved-view source operations for Bases. Both remain
defined below for collections that do not list `base` as a record extension.
They are transitional: they are removed in the release that removes the
saved-view source operations for canonical views, and no new consumer should
adopt them.

## Sources

Obsidian `.base` files are external saved-view sources. A collection provider
discovers configured sources and exposes them through the saved-view operations
in [Operations](../12-operations.md). Core Read continues to discover records
through the collection's record extensions.

Collections enable discovery with a namespaced configuration section:

```yaml
x-obsidian:
bases:
include:
- TaskNotes/Views/**/*.base
create_folder: TaskNotes/Views
default_for_new_views: true
```

`include` contains collection-relative globs as defined in
[Collection Layout](../02-collection-layout.md). The provider MUST apply
the same path-boundary and symlink protections used for record discovery.
`create_folder` identifies the preferred location for new Obsidian sources.
`default_for_new_views` makes that source format the collection's default when
a view-creation interface offers no explicit format. Providers advertising
write support use these values when creating a source.

Write-capable providers validate the complete `.base` document before a
source operation commits it. They preserve unknown top-level keys, view keys,
## Discovery and extension opt-in

A provider discovers view sources from records whose matched type implements
`obsidian.base`. Discovery MUST NOT use a separate path scan or side list. A path
glob can match a record to a type, as above, but the implemented contract is what
makes that record a view source. The contract itself grants no read, execute, or
write authority; ordinary record grants still apply.

The `obsidian.base` catalog pack provides the managed contract and a seeded,
user-editable `obsidian_base` type matching `**/*.base`. A pack that depends on it
(such as TaskNotes) can seed additional view records. Seeded view records are
user-owned and MUST NOT be overwritten on upgrade; user-created Base records
are discovered by the same contract rule.

`.base` is not a global record-extension default or a special resource kind.
The pack declares, through its `setup.configuration` collection-setup envelope,
a requirement that `/settings/record_extensions` contains `"base"`, with a
`set_add` provision for `"base"`. Assessment shows this addition before apply;
apply preserves the effective `md` default and existing extensions. Uninstall
MUST NOT silently remove the extension. Without that opt-in, `.base` files are
not records and MUST NOT become views through an alternate discovery path.
Record discovery retains the path-boundary and symlink protections in
[Collection Layout](../02-collection-layout.md).

The older `x-obsidian.bases.include` discovery mechanism and saved-view source
mutation operations are superseded, not an alternative when the extension is
disabled. Bases use ordinary record create, update, rename, and delete operations;
no separate include list, creation-folder setting, or source-operation path is
required.

Record writers validate the complete Base document before a record mutation
commits it. They preserve unknown top-level keys, view keys,
property metadata, formulas, and presentation options supplied in the
document. A source editor can therefore modify the structures it understands
while round-tripping the remainder.

The `.base` file remains authoritative for a discovered Obsidian source.
The Base record remains authoritative for a discovered Obsidian source.
`list_views` returns `source.format: obsidian.base`, a revision derived from the
source bytes, and a stable named-view ID for each contained view. Stable IDs are
derived deterministically from view names when the source format supplies no
Expand Down Expand Up @@ -124,7 +121,7 @@ context before calling the query or view executor.
An implementation advertises `obsidian_bases_views` through
`optional_features` when it:

- discovers `.base` sources selected by `x-obsidian.bases.include`
- discovers record sources whose matched type implements `obsidian.base`
- assigns deterministic named-view IDs and source revisions
- parses filters and formulas before candidate evaluation
- evaluates the Obsidian Bases expression dialect, including formula
Expand All @@ -134,7 +131,7 @@ An implementation advertises `obsidian_bases_views` through
- applies source order, sort, group, limit, and presentation metadata
- exposes the source's ordered properties and display names
- returns the saved-view headless result envelope
- keeps `.base` sources authoritative throughout discovery and execution
- keeps Base records authoritative throughout discovery and execution

Conformance suites for `obsidian_bases_views` MUST include an oracle corpus
captured from the supported Obsidian expression environment. Each case records
Expand Down
Loading