skills.rest
bluesky-social
bluesky-socialOFFICIAL
Explore all skills by this author →
GitHub

lex-data

Parse, serialize, hash, and validate AT Protocol data values with @atproto/lex.

9.6k|915|Updated Dec 17, 2021
Search Tags:#serialization#lexicon#Data Model#typeScript#ATProto#cid#cbOR
One-click install
npx skills add https://github.com/bluesky-social/atproto --skill lex-data
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: lex-data
Source: https://github.com/bluesky-social/atproto/tree/main/.agents/skills/lex-data
Command: npx skills add https://github.com/bluesky-social/atproto --skill lex-data

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Working with AT Protocol data requires handling CIDs, raw bytes, CBOR encoding, blob references, and branded identifier strings correctly, and hand-rolled approaches with multiformats, toISOString(), or ad-hoc base64 produce subtle bugs and invalid records.

Core Features & Use Cases

  • CID and bytes handling: Parse, validate, and create CIDs with flavor constraints (raw, cbor, dasl), and convert binary data with base64 helpers, replacing direct multiformats usage.
  • JSON and CBOR conversion: Convert between JSON strings, plain objects, and Lex values with lexParse/lexStringify, and encode deterministic CBOR (DRISL) for repo storage, CAR files, and event frames.
  • Identifier and datetime types: Brand DIDs, handles, AT URIs, NSIDs, TIDs, and datetimes with nominal types and guards so unvalidated strings cannot leak into records or database rows.
  • Use Case: When writing a PDS record, use cidForLex to hash the CBOR-encoded record, currentDatetimeString() instead of new Date().toISOString() for createdAt, and enumBlobRefs to walk the record for blob references.

Quick Start

Ask the AI to serialize an AT Protocol record to CBOR and compute its CID using @atproto/lex and @atproto/lex-cbor.

Frequently Asked Questions about lex-data

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a CID for an AT Protocol record in TypeScript?▼

Use cidForLex from @atproto/lex-cbor, which CBOR-encodes the value and hashes it asynchronously via WebCrypto. For blob content use cidForRawBytes, and for already-CBOR bytes use cidForCbor.

How do I convert between JSON and Lex values in @atproto/lex?▼

Use lexParse to turn a JSON string into a LexValue with Cid and Uint8Array instances, and lexStringify for the reverse. jsonToLex and lexToJson convert already-parsed plain objects, and all accept a strict option for untrusted input.

Why is my AT Protocol datetime string rejected?▼

Date.prototype.toISOString() is not guaranteed to conform because years outside 0-9999 serialize with an expanded prefix. Route Date objects through toDatetimeString or use currentDatetimeString() from @atproto/lex instead.

Does @atproto/lex include CBOR encoding functions?▼

No, @atproto/lex does not re-export CBOR functions. Add @atproto/lex-cbor as an explicit dependency to use encode, decode, decodeAll, and cidForLex for DRISL deterministic encoding.

How do I handle legacy blob references when reading records?▼

Use the format-agnostic accessors getBlobCid, getBlobCidString, getBlobMime, and getBlobSize, which work on both typed and legacy blob refs. Pass allowLegacy: true to enumBlobRefs when deep-walking records that may contain legacy shapes.

When should I use isLexValue versus schema validation?▼

isLexValue walks the entire structure, rejecting cycles, non-integer numbers, and non-plain objects, so it is expensive on hot paths. Where a Lexicon schema already validates the value, skip isLexValue and rely on the schema check.

Related Skills

Explore More Software Engineering Skills→
maragudkmaragudk
27

atproto

Describes how to build on the AT Protocol with Lexicons, XRPC, and firehose.

Official
Advanced
ngerakinesngerakines
46

atproto-publish-lexicon

Publish and resolve AT Protocol lexicons as com.atproto.lexicon.schema records.

Community
Advanced
maxvaegamaxvaega
146

invalid-version-type

Validate skill metadata version fields as strings during loading.

Community
Basic
GainForestGainForest
1

gainforest-oauth-setup

Automate ATProto OAuth integration in Next.js App Router apps with Supabase session storage.

Official
Advanced