Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
50 changes: 11 additions & 39 deletions 12-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,6 @@ Optional saved-view operations:

- list_views
- execute_view
- read_view_source
- create_view_source
- update_view_source
- delete_view_source

## Read

Expand Down Expand Up @@ -261,8 +257,9 @@ diagnostics: []

`source.path` is a collection-relative path. `source.format` is a stable source
format identifier. `source.revision` is an opaque token for the source content.
`source.writable` describes whether the provider accepts writes for that source
format. Each nested descriptor exposes the stable named-view ID, its display
`source.writable` is true when the source is a record, whose type implements
`mdbase.view` or `obsidian.base`, and is edited with the record operations.
It is false for a source that is not a record. Each nested descriptor exposes the stable named-view ID, its display
name, and its optional presentation metadata. Discovery order is ascending by
source path and then source-defined named-view order.

Expand Down Expand Up @@ -298,40 +295,15 @@ source's declared expression dialect and returns the query result envelope with
`render: false` requests the headless result and is the default. `render: true`
requests renderer output using the selected presentation metadata.

### Saved-view source operations
### Editing saved views

A provider that advertises a source as `writable: true` MUST support the four
saved-view source operations. These operations exchange the complete source
document so format-aware editors can preserve source data they do not
interpret.

`read_view_source` accepts a `path` from `list_views` and returns:

```yaml
path: TaskNotes/Views/tasks.base
format: obsidian.base
revision: sha256:opaque
document: |
views:
- type: tasknotesTaskList
name: Tasks
```

`create_view_source` accepts `document` and may accept `path`, `format`, and
`name`. When `path` is absent, the provider selects a collection-relative path
using the requested format and the collection's format configuration. Creation
MUST validate the complete document and MUST fail with `path_conflict` rather
than replace an existing source.

`update_view_source` accepts `path`, `document`, and optional `if_revision`.
The complete candidate document MUST be valid before the current source is
atomically replaced. `delete_view_source` accepts `path` and optional
`if_revision`.

All source operations apply the collection's path-boundary and symlink rules.
Update and delete use the concurrency behavior defined below. A successful
create or update returns the same fields as `read_view_source`; a successful
delete returns `path` and `deleted: true`.
Saved views are records (Chapter 05a), so they have no dedicated write
operations. A client edits a source whose `source.writable` is true with the
record operations: `read` with `include_document` returns the complete source,
`update` with `document` replaces it exactly as supplied, preserving source
data the client does not interpret, and `create` and `delete` add and remove
sources. The record operations apply their ordinary validation, path-boundary,
symlink and concurrency rules.

## Concurrency

Expand Down
12 changes: 0 additions & 12 deletions 14-conformance.md
Original file line number Diff line number Diff line change
Expand Up @@ -310,18 +310,6 @@ An implementation advertises `obsidian_bases_views` through
`optional_features` when it meets the requirements of the
[Obsidian Bases adapter](./adapters/obsidian-bases.md).

An implementation advertises `writable_view_sources` through
`optional_features` when it:

- marks only writable source formats with `source.writable: true`
- reads complete source documents with stable opaque revisions
- validates complete candidate documents before create or update
- creates sources without replacing an existing path
- applies `if_revision` to update and delete
- writes source replacements atomically
- preserves source-format extension data supplied by the caller
- makes successful mutations visible to subsequent list and execute operations

## Links Requirements

Links implementations MUST:
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ All notable changes to this specification and conformance suite are documented h

## Unreleased

### Saved views are edited with the record operations

- `read_view_source`, `create_view_source`, `update_view_source` and
`delete_view_source`, and the `writable_view_sources` feature, are removed.
Saved views are records claimed through `mdbase.view` or `obsidian.base`,
edited with `read` (`include_document`), `update` (`document`), `create` and
`delete`. `list_views` reports `source.writable: true` for sources that are
records. `view_changed` remains for configured sources that are not records.

### YAML document records and Bases as records

- A record's format is fixed by its extension through a table in the
Expand Down
25 changes: 12 additions & 13 deletions adapters/obsidian-bases.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,13 @@ 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
The type's path match replaces `x-obsidian.bases.include`, which remains
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 discovered that way are not records: they are listed and executed but
report `source.writable: false`, and changes to them are reported as
`view_changed`. Configured discovery is transitional and no new consumer should
adopt it; it is removed, with `view_changed`, once collections have adopted
Bases as records.

## Sources

Expand All @@ -67,14 +68,12 @@ x-obsidian:
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,
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.
a view-creation interface offers no explicit format.

A writer that replaces a Base record with a whole-document `update` preserves
unknown top-level keys, view keys, property metadata, formulas, and
presentation options, so a source editor can modify the structures it
understands while round-tripping the remainder.

The `.base` file remains authoritative for a discovered Obsidian source.
`list_views` returns `source.format: obsidian.base`, a revision derived from the
Expand Down
Loading