Semble Lexicon Reference

This document provides a complete reference for Semble’s ATProto lexicons (data schemas).

Alpha documentation generated with Claude Code and edited by the Cosmik team. Subject to revision as the project stabilizes

Overview

Semble uses three primary lexicon collections in the network.cosmik namespace:

  • network.cosmik.card - URL bookmarks and notes

  • network.cosmik.collection - Named collections for organizing cards

  • network.cosmik.collectionLink - Many-to-many links between cards and collections

network.cosmik.card

Cards are the core record type in Semble, representing bookmarked URLs and associated notes.

Card Types

Cards come in two types, distinguished by the type field:

  1. URL Cards (type: "URL") - Bookmark a URL with metadata

  2. NOTE Cards (type: "NOTE") - Add notes to existing URL cards

URL Card Structure

{
  "type": "URL",
  "$type": "network.cosmik.card",
  "content": {
    "url": "https://example.com/article",
    "$type": "network.cosmik.card#urlContent",
    "metadata": {
      "type": "article",
      "$type": "network.cosmik.card#urlMetadata",
      "title": "Example Article Title",
      "description": "Article description or excerpt...",
      "author": "Author Name",
      "siteName": "Example Site",
      "imageUrl": "https://example.com/image.jpg",
      "publishedDate": "2025-01-15T10:30:00.000Z",
      "retrievedAt": "2025-01-15T12:00:00.000Z"
    }
  },
  "createdAt": "2025-01-15T12:00:00.000Z",
  "provenance": {
    "via": {
      "uri": "at://did:plc:xxx/network.cosmik.card/zzz",
      "cid": "bafyrei..."
    },
    "$type": "network.cosmik.defs#provenance"
  }
}

URL Card Fields

Field
Type
Required
Description

type

string

Yes

Always "URL" for URL cards

$type

string

Yes

Always "network.cosmik.card"

content

object

Yes

Contains the URL and metadata

content.url

string

Yes

The bookmarked URL

content.$type

string

Yes

Always "network.cosmik.card#urlContent"

content.metadata

object

No

Fetched metadata about the URL

content.metadata.type

string

No

Content type: "video", "article", "image", "website", etc.

content.metadata.title

string

No

Page or content title

content.metadata.description

string

No

Page description or excerpt

content.metadata.author

string

No

Content author

content.metadata.siteName

string

No

Website name

content.metadata.imageUrl

string

No

Preview image URL

content.metadata.publishedDate

string

No

ISO 8601 datetime of original publication

content.metadata.retrievedAt

string

No

ISO 8601 datetime when metadata was fetched

createdAt

string

Yes

ISO 8601 datetime when card was created

provenance

object

No

Tracks how this card was discovered in the network

provenance.via

object

No

Reference to the card from which this one was collected

provenance.via.uri

string

No

AT-URI of the source card

provenance.via.cid

string

No

Content ID of the source card

provenance.$type

string

No

Always "network.cosmik.defs#provenance"

Note: The provenance field enables tracking how cards are discovered and shared across the network, supporting notifications when someone collects your card.

NOTE Card Structure

NOTE cards attach textual notes to existing URL cards via a parent reference.

NOTE Card Fields

Field
Type
Required
Description

type

string

Yes

Always "NOTE" for note cards

$type

string

Yes

Always "network.cosmik.card"

content

object

Yes

Contains the note text

content.text

string

Yes

The note content

content.$type

string

Yes

Always "network.cosmik.card#noteContent"

url

string

No

May contain the parent card's URL

parentCard

object

Yes

Reference to the parent URL card

parentCard.uri

string

Yes

AT-URI of parent card (e.g., at://did:plc:xxx/network.cosmik.card/yyy)

parentCard.cid

string

Yes

Content ID (CID) of parent card

createdAt

string

Yes

ISO 8601 datetime when note was created

Design Notes

  • URL cards store the primary bookmark and fetched metadata

  • NOTE cards attach to URL cards via parentCard reference

  • A URL card currently can only have a single NOTE card attached

  • When displaying cards, NOTE cards should be shown attached to their parent URL card, not as separate items

network.cosmik.collection

Collections are named groups for organizing cards.

Collection Structure

Collection Fields

Field
Type
Required
Description

$type

string

Yes

Always "network.cosmik.collection"

name

string

Yes

Collection name

description

string

No

Optional description

createdAt

string

Yes

ISO 8601 datetime when created

network.cosmik.collectionLink

CollectionLinks establish many-to-many relationships between cards and collections.

CollectionLink Structure

CollectionLink Fields

Field
Type
Required
Description

$type

string

Yes

Always "network.cosmik.collectionLink"

card

object

Yes

Reference to a card

card.uri

string

Yes

AT-URI of the card

card.cid

string

Yes

Content ID of the card

collection

object

Yes

Reference to a collection

collection.uri

string

Yes

AT-URI of the collection

collection.cid

string

Yes

Content ID of the collection

createdAt

string

Yes

ISO 8601 datetime when link was created

Design Notes

  • One card can belong to multiple collections (many-to-many)

  • One collection can contain multiple cards

  • Links are stored as separate records, not embedded in cards or collections

  • To find all cards in a collection, query for collectionLinks with matching collection.uri

  • To find all collections for a card, query for collectionLinks with matching card.uri

Working with References

ATProto uses strong references containing both URI and CID:

  • URI: Unique identifier in the format at://[DID]/[collection]/[rkey]

  • CID: Content-addressed identifier ensuring data integrity

When building relationships (like collectionLinks or parentCard), you'll need to extract the URI from records and construct these reference objects.

Exmple: Complete Card with Collection

Here's a complete example showing all record types working together:

URL Card:

NOTE Card (attached to above):

Collection:

CollectionLink (linking card to collection):

PreviousGetting Started with the Semble PDS Client

Last updated