diff --git a/spec.md b/spec.md index 023efa9..491cfd2 100644 --- a/spec.md +++ b/spec.md @@ -7,7 +7,7 @@ Informal community spec, seeking feedback. The proposed syntax is *mostly* compatible with Constellation's `source` record field locator syntax. Constellation uses a `:` format for its `source` parameter; *RecordPath* will replace the `` part. -While the driving motivation for this spec is lexicon-agnostic backlink indexing, it being able to canonically reference field locations in records is broadly useful. +While the driving motivation for this spec is lexicon-agnostic backlink indexing, being able to canonically reference field locations in records is broadly useful. > [!TIP] > For example: [Graze Turbostream](https://help.graze.social/en/article/graze-turbostream-1cmhebt/) resolves references from Bluesky posts into a richly-hydrated firehose, an incredibly useful enhancement. @@ -70,7 +70,7 @@ A RecordPath is a sequence of field names separated by `.`. For a Bluesky "like" The RecordPaths are: ``` -$type -- selects: "app.bsky.fee.like" +$type -- selects: "app.bsky.feed.like" createdAt -- "2026-04-15T00:00:00.000Z" subject -- the entire { uri: .., cid: ..} sub-object subject.uri -- "at://did:plc:pxa3amkp7jhfclaads3zud7q/app.bsky.feed.post/3mjkx2hpvqc2t" @@ -209,3 +209,24 @@ The RecordPath `embed{app.bsky.embed.external}.uri` reaches the quoted post's ex ## 3. Data-model assumptions RecordPath depends on several properties of the atproto [data model](https://atproto.com/specs/data-model) and [lexicon](https://atproto.com/specs/lexicon) system. + +### `$type` is on unions (and blobs), not on plain object refs + +- **Records** include `$type` at the top level (not included in RecordPaths) +- **Union variants** MUST include `$type` (consistent with lexicon spec) +- **Plain (non-union) object refs**: Lexicon states `$type` *"should not be included in encoded data as a discriminator."* + Since this is only a "should-not" and not a "must-not", valid records are technically allowed to have a `$type` where they shouldn't, and we aren't guaranteed to have a canonical RecordPath for every valid atproto record field. + Hopefully record serializers are following this SHOULD :/ + +### Forward-compatibility + +Lexicon evolution rules forbid **type changes** across schema revisions, so a plain object ref cannot be converted to a union in a lexicon-forward-compatibility-compliant revision under the same NSID, so RecordPath canonicalization is hopefully safe from forward-compatible lexicon changes. + + +todo: + +- api recommendations for scalar vs vector queries + + > A RecordPath is *scalar* if it contains no `[]` qualifiers, otherwise *vector*. Implementations that evaluate RecordPaths against records typically expose apis for blah blah + + - maybe compare to DOM `querySelector` / `querySelectorAll`