feature: Added lexicon community lexicons

Signed-off-by: Nick Gerakines <[e-mail]>

Cargo.lock

···
 checksum = "c469d952047f47f91b68d1cba3f10d63c11d73e4636f24f08daf0278abf01c4d"
 dependencies = [
  "num-traits",
+ "serde",
 ]
 
 [[package]]

crates/atproto-oauth/src/jwk.rs

···
 
         // Ensure reasonable performance (should complete in well under a second)
         assert!(
-            duration.as_millis() < 5000,
+            duration.as_millis() < 10000,
             "Performance test took too long: {:?}",
             duration
         );

crates/atproto-record/Cargo.toml

···
 thiserror.workspace = true
 
 tokio = { workspace = true, optional = true }
-chrono = {version = "0.4.41", default-features = false, features = ["std", "now"]}
+chrono = {version = "0.4.41", default-features = false, features = ["std", "now", "serde"]}
 clap = { workspace = true, optional = true }
 
 [features]

crates/atproto-record/src/aturi.rs

···
 //!
 //! This module provides functionality to parse and validate AT Protocol URIs (AT-URIs),
 //! which are used to uniquely identify records within the AT Protocol ecosystem.
-//! 
+//!
 //! ## AT-URI Format
 //!
 //! AT-URIs follow the format: `at://authority/collection/record_key`
···
 ///
 /// AT-URIs uniquely identify records within AT Protocol repositories by combining
 /// three essential components: authority (DID), collection (NSID), and record key.
-/// 
+///
 /// This struct provides validated access to these components after successful parsing
 /// and implements `Display` for reconstructing the original URI format.
 #[cfg_attr(debug_assertions, derive(Debug))]

crates/atproto-record/src/bytes.rs

···
+//! Byte array serialization utilities for AT Protocol records.
+//!
+//! This module provides specialized Serde serialization and deserialization functions
+//! for byte arrays (`Vec<u8>`), handling base64 encoding as required by the AT Protocol
+//! lexicon specifications for binary data fields.
+//!
+//! ## Usage
+//!
+//! The `format` module is designed to be used with Serde's `#[serde(with = "...")]` attribute
+//! on fields that contain binary data:
+//!
+//! ```ignore
+//! use serde::{Deserialize, Serialize};
+//!
+//! #[derive(Serialize, Deserialize)]
+//! struct Signature {
+//!     #[serde(rename = "$bytes", with = "atproto_record::bytes::format")]
+//!     signature: Vec<u8>,
+//! }
+//! ```
+//!
+//! ## Base64 Encoding
+//!
+//! The serialization uses standard base64 encoding (RFC 4648) with padding,
+//! compatible with the `$bytes` field format used throughout AT Protocol.
+
+/// Base64 serialization format for byte arrays.
+///
+/// This module provides serde serialization/deserialization for `Vec<u8>` values,
+/// encoding them as base64 strings during JSON serialization and decoding them
+/// back to byte vectors during deserialization. This is the standard format
+/// for binary data in AT Protocol lexicon structures.
+pub mod format {
+    use serde::{Deserialize, Serialize};
+    use serde::{Deserializer, Serializer};
+
+    use base64::{Engine, engine::general_purpose::STANDARD};
+
+    /// Serializes a byte vector to a base64 encoded string.
+    pub fn serialize<S: Serializer>(value: &Vec<u8>, serializer: S) -> Result<S::Ok, S::Error> {
+        let encoded_value = STANDARD.encode(&value);
+        String::serialize(&encoded_value, serializer)
+    }
+
+    /// Deserializes a base64 encoded string to a byte vector.
+    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<u8>, D::Error> {
+        let encoded_value = String::deserialize(d)?;
+        STANDARD
+            .decode(encoded_value)
+            .map_err(|e| serde::de::Error::custom(e))
+    }
+}

crates/atproto-record/src/lexicon/com_atproto_repo.rs

···
+//! Core AT Protocol repository types.
+//!
+//! This module contains fundamental types for the AT Protocol repository
+//! system, including strong references that combine URIs with content
+//! identifiers for immutable referencing.
+
+use crate::typed::{LexiconType, TypedLexicon};
+use serde::{Deserialize, Serialize};
+
+/// The namespace identifier for strong references
+pub const STRONG_REF_NSID: &str = "com.atproto.repo.strongRef";
+
+/// Strong reference to an AT Protocol record.
+///
+/// A strong reference combines an AT URI with a CID (Content Identifier),
+/// providing both a location and a content hash. This ensures that the
+/// reference points to a specific, immutable version of a record.
+///
+/// Strong references are commonly used to:
+/// - Reference specific versions of records
+/// - Create immutable links between records
+/// - Ensure content integrity through CID verification
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::com::atproto::repo::{StrongRef, TypedStrongRef};
+///
+/// let strong_ref = StrongRef {
+///     uri: "at://did:plc:example/app.bsky.feed.post/3k4duaz5vfs2b".to_string(),
+///     cid: "bafyreib55ro5klxlwfxc5hzfonpdog6donvqvwdvjbloffqrmkenbqgpde".to_string(),
+/// };
+///
+/// // Use TypedStrongRef for automatic $type field handling
+/// let typed_ref = TypedStrongRef::new(strong_ref);
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct StrongRef {
+    /// AT URI pointing to a specific record
+    /// Format: at://[did]/[collection]/[rkey]
+    pub uri: String,
+    /// Content Identifier (CID) of the record
+    /// This ensures the reference points to a specific, immutable version
+    pub cid: String,
+}
+
+impl LexiconType for StrongRef {
+    fn lexicon_type() -> &'static str {
+        STRONG_REF_NSID
+    }
+}
+
+/// Type alias for StrongRef with automatic $type field handling.
+///
+/// This type wrapper ensures that the `$type` field is automatically
+/// added during serialization and validated during deserialization.
+pub type TypedStrongRef = TypedLexicon<StrongRef>;

crates/atproto-record/src/lexicon/community_lexicon_attestation.rs

···
+//! Attestation and signature types for AT Protocol.
+//!
+//! This module provides types for cryptographic signatures and attestations
+//! that can be attached to records to prove authenticity, authorization,
+//! or other properties.
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::lexicon::Bytes;
+use crate::lexicon::com_atproto_repo::TypedStrongRef;
+use crate::typed::{LexiconType, TypedLexicon};
+
+/// The namespace identifier for signatures
+pub const NSID: &str = "community.lexicon.attestation.signature";
+
+/// Enum that can hold either a signature reference or an inline signature.
+///
+/// This type allows signatures to be either embedded directly in a record
+/// or referenced via a strong reference. This flexibility enables:
+/// - Inline signatures for immediate verification
+/// - Referenced signatures for deduplication and separate storage
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::attestation::{SignatureOrRef, create_typed_signature};
+/// use atproto_record::lexicon::Bytes;
+///
+/// // Inline signature
+/// let inline = SignatureOrRef::Inline(create_typed_signature(
+///     "did:plc:issuer".to_string(),
+///     Bytes { bytes: b"signature".to_vec() },
+/// ));
+///
+/// // Referenced signature
+/// let reference = SignatureOrRef::Reference(typed_strong_ref);
+/// ```
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+#[serde(untagged)]
+pub enum SignatureOrRef {
+    /// A reference to a signature stored elsewhere
+    Reference(TypedStrongRef),
+    /// An inline signature
+    Inline(TypedSignature),
+}
+
+/// A vector of signatures that can be either inline or referenced.
+///
+/// This type alias is commonly used in records that support multiple
+/// signatures, such as badges, awards, and RSVPs.
+pub type Signatures = Vec<SignatureOrRef>;
+
+/// Cryptographic signature structure.
+///
+/// Represents a signature created by an issuer (identified by DID) over
+/// some data. The signature can be used to verify authenticity, authorization,
+/// or other properties of the signed content.
+///
+/// # Fields
+///
+/// - `issuer`: DID of the entity that created the signature
+/// - `signature`: The actual signature bytes
+/// - `extra`: Additional fields that may be present in the signature
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::attestation::Signature;
+/// use atproto_record::lexicon::Bytes;
+/// use std::collections::HashMap;
+///
+/// let sig = Signature {
+///     issuer: "did:plc:example".to_string(),
+///     signature: Bytes { bytes: b"signature_bytes".to_vec() },
+///     extra: HashMap::new(),
+/// };
+/// ```
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+pub struct Signature {
+    /// DID of the entity that created this signature
+    pub issuer: String,
+
+    /// The cryptographic signature bytes
+    pub signature: Bytes,
+
+    /// Additional fields for extensibility
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl LexiconType for Signature {
+    fn lexicon_type() -> &'static str {
+        NSID
+    }
+
+    /// Type field is optional for signatures since they may appear without it
+    fn type_required() -> bool {
+        false
+    }
+}
+
+/// Type alias for Signature with automatic $type field handling.
+///
+/// This wrapper ensures proper serialization/deserialization of the
+/// `$type` field when present.
+pub type TypedSignature = TypedLexicon<Signature>;
+
+/// Helper function to create a typed signature.
+///
+/// Creates a new signature with the TypedLexicon wrapper, ensuring
+/// proper `$type` field handling.
+///
+/// # Arguments
+///
+/// * `issuer` - DID of the signature issuer
+/// * `signature` - The signature bytes
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::attestation::create_typed_signature;
+/// use atproto_record::lexicon::Bytes;
+///
+/// let sig = create_typed_signature(
+///     "did:plc:issuer".to_string(),
+///     Bytes { bytes: b"sig_data".to_vec() },
+/// );
+/// ```
+pub fn create_typed_signature(issuer: String, signature: Bytes) -> TypedSignature {
+    TypedLexicon::new(Signature {
+        issuer,
+        signature,
+        extra: HashMap::new(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::lexicon::com_atproto_repo::StrongRef;
+    use serde_json::json;
+
+    #[test]
+    fn test_signature_deserialization() {
+        let json_str = r#"{
+            "$type": "community.lexicon.attestation.signature",
+            "issuer": "did:plc:test123",
+            "signature": {"$bytes": "dGVzdCBzaWduYXR1cmU="}
+        }"#;
+
+        let signature: Signature = serde_json::from_str(json_str).unwrap();
+
+        assert_eq!(signature.issuer, "did:plc:test123");
+        assert_eq!(signature.signature.bytes, b"test signature");
+        // The $type field will be captured in extra due to #[serde(flatten)]
+        assert_eq!(signature.extra.len(), 1);
+        assert!(signature.extra.contains_key("$type"));
+    }
+
+    #[test]
+    fn test_signature_deserialization_with_extra_fields() {
+        let json_str = r#"{
+            "$type": "community.lexicon.attestation.signature",
+            "issuer": "did:plc:test123",
+            "signature": {"$bytes": "dGVzdCBzaWduYXR1cmU="},
+            "issuedAt": "2024-01-01T00:00:00.000Z",
+            "purpose": "verification"
+        }"#;
+
+        let signature: Signature = serde_json::from_str(json_str).unwrap();
+
+        assert_eq!(signature.issuer, "did:plc:test123");
+        assert_eq!(signature.signature.bytes, b"test signature");
+        // 3 extra fields: $type, issuedAt, purpose
+        assert_eq!(signature.extra.len(), 3);
+        assert!(signature.extra.contains_key("$type"));
+        assert_eq!(
+            signature.extra.get("issuedAt").unwrap(),
+            "2024-01-01T00:00:00.000Z"
+        );
+        assert_eq!(signature.extra.get("purpose").unwrap(), "verification");
+    }
+
+    #[test]
+    fn test_signature_serialization() {
+        let mut extra = HashMap::new();
+        extra.insert("custom_field".to_string(), json!("custom_value"));
+
+        let signature = Signature {
+            issuer: "did:plc:serializer".to_string(),
+            signature: Bytes {
+                bytes: b"hello world".to_vec(),
+            },
+            extra,
+        };
+
+        let json = serde_json::to_value(&signature).unwrap();
+
+        // Without custom Serialize impl, $type is not automatically added
+        assert!(!json.as_object().unwrap().contains_key("$type"));
+        assert_eq!(json["issuer"], "did:plc:serializer");
+        // "hello world" base64 encoded is "aGVsbG8gd29ybGQ="
+        assert_eq!(json["signature"]["$bytes"], "aGVsbG8gd29ybGQ=");
+        assert_eq!(json["custom_field"], "custom_value");
+    }
+
+    #[test]
+    fn test_signature_round_trip() {
+        let original = Signature {
+            issuer: "did:plc:roundtrip".to_string(),
+            signature: Bytes {
+                bytes: b"round trip test".to_vec(),
+            },
+            extra: HashMap::new(),
+        };
+
+        // Serialize to JSON
+        let json = serde_json::to_string(&original).unwrap();
+
+        // Deserialize back
+        let deserialized: Signature = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(original.issuer, deserialized.issuer);
+        assert_eq!(original.signature.bytes, deserialized.signature.bytes);
+        // Without the custom Serialize impl, no $type is added
+        // so the round-trip preserves the empty extra map
+        assert_eq!(deserialized.extra.len(), 0);
+    }
+
+    #[test]
+    fn test_signature_with_complex_extra_fields() {
+        let mut extra = HashMap::new();
+        extra.insert("timestamp".to_string(), json!(1234567890));
+        extra.insert(
+            "metadata".to_string(),
+            json!({
+                "version": "1.0",
+                "algorithm": "ES256"
+            }),
+        );
+        extra.insert("tags".to_string(), json!(["tag1", "tag2", "tag3"]));
+
+        let signature = Signature {
+            issuer: "did:plc:complex".to_string(),
+            signature: Bytes {
+                bytes: vec![0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA],
+            },
+            extra,
+        };
+
+        let json = serde_json::to_value(&signature).unwrap();
+
+        // Without custom Serialize impl, $type is not automatically added
+        assert!(!json.as_object().unwrap().contains_key("$type"));
+        assert_eq!(json["issuer"], "did:plc:complex");
+        assert_eq!(json["timestamp"], 1234567890);
+        assert_eq!(json["metadata"]["version"], "1.0");
+        assert_eq!(json["metadata"]["algorithm"], "ES256");
+        assert_eq!(json["tags"], json!(["tag1", "tag2", "tag3"]));
+    }
+
+    #[test]
+    fn test_empty_signature() {
+        let signature = Signature {
+            issuer: String::new(),
+            signature: Bytes { bytes: Vec::new() },
+            extra: HashMap::new(),
+        };
+
+        let json = serde_json::to_value(&signature).unwrap();
+
+        // Without custom Serialize impl, $type is not automatically added
+        assert!(!json.as_object().unwrap().contains_key("$type"));
+        assert_eq!(json["issuer"], "");
+        assert_eq!(json["signature"]["$bytes"], ""); // Empty bytes encode to empty string
+    }
+
+    #[test]
+    fn test_signatures_vec_serialization() {
+        // Test with plain Vec<Signature> for basic signature serialization
+        let signatures: Vec<Signature> = vec![
+            Signature {
+                issuer: "did:plc:first".to_string(),
+                signature: Bytes {
+                    bytes: b"first".to_vec(),
+                },
+                extra: HashMap::new(),
+            },
+            Signature {
+                issuer: "did:plc:second".to_string(),
+                signature: Bytes {
+                    bytes: b"second".to_vec(),
+                },
+                extra: HashMap::new(),
+            },
+        ];
+
+        let json = serde_json::to_value(&signatures).unwrap();
+
+        assert!(json.is_array());
+        assert_eq!(json.as_array().unwrap().len(), 2);
+        assert_eq!(json[0]["issuer"], "did:plc:first");
+        assert_eq!(json[1]["issuer"], "did:plc:second");
+    }
+
+    #[test]
+    fn test_signatures_as_signature_or_ref_vec() {
+        // Test the new Signatures type with inline signatures
+        let signatures: Signatures = vec![
+            SignatureOrRef::Inline(create_typed_signature(
+                "did:plc:first".to_string(),
+                Bytes {
+                    bytes: b"first".to_vec(),
+                },
+            )),
+            SignatureOrRef::Inline(create_typed_signature(
+                "did:plc:second".to_string(),
+                Bytes {
+                    bytes: b"second".to_vec(),
+                },
+            )),
+        ];
+
+        let json = serde_json::to_value(&signatures).unwrap();
+
+        assert!(json.is_array());
+        assert_eq!(json.as_array().unwrap().len(), 2);
+        assert_eq!(json[0]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json[0]["issuer"], "did:plc:first");
+        assert_eq!(json[1]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json[1]["issuer"], "did:plc:second");
+    }
+
+    #[test]
+    fn test_typed_signature_serialization() {
+        let typed_sig = create_typed_signature(
+            "did:plc:typed".to_string(),
+            Bytes {
+                bytes: b"typed signature".to_vec(),
+            },
+        );
+
+        let json = serde_json::to_value(&typed_sig).unwrap();
+
+        assert_eq!(json["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json["issuer"], "did:plc:typed");
+        // "typed signature" base64 encoded
+        assert_eq!(json["signature"]["$bytes"], "dHlwZWQgc2lnbmF0dXJl");
+    }
+
+    #[test]
+    fn test_typed_signature_deserialization() {
+        let json = json!({
+            "$type": "community.lexicon.attestation.signature",
+            "issuer": "did:plc:typed",
+            "signature": {"$bytes": "dHlwZWQgc2lnbmF0dXJl"}
+        });
+
+        let typed_sig: TypedSignature = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed_sig.inner.issuer, "did:plc:typed");
+        assert_eq!(typed_sig.inner.signature.bytes, b"typed signature");
+        assert!(typed_sig.has_type_field());
+        assert!(typed_sig.validate().is_ok());
+    }
+
+    #[test]
+    fn test_typed_signature_without_type_field() {
+        let json = json!({
+            "issuer": "did:plc:notype",
+            "signature": {"$bytes": "bm8gdHlwZQ=="}  // "no type" in base64
+        });
+
+        let typed_sig: TypedSignature = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed_sig.inner.issuer, "did:plc:notype");
+        assert_eq!(typed_sig.inner.signature.bytes, b"no type");
+        assert!(!typed_sig.has_type_field());
+        // Validation should still pass because type_required() returns false for Signature
+        assert!(typed_sig.validate().is_ok());
+    }
+
+    #[test]
+    fn test_typed_signature_with_extra_fields() {
+        let mut sig = Signature {
+            issuer: "did:plc:extra".to_string(),
+            signature: Bytes {
+                bytes: b"extra test".to_vec(),
+            },
+            extra: HashMap::new(),
+        };
+        sig.extra
+            .insert("customField".to_string(), json!("customValue"));
+        sig.extra.insert("timestamp".to_string(), json!(1234567890));
+
+        let typed_sig = TypedLexicon::new(sig);
+
+        let json = serde_json::to_value(&typed_sig).unwrap();
+
+        assert_eq!(json["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json["issuer"], "did:plc:extra");
+        assert_eq!(json["customField"], "customValue");
+        assert_eq!(json["timestamp"], 1234567890);
+    }
+
+    #[test]
+    fn test_typed_signature_round_trip() {
+        let original = Signature {
+            issuer: "did:plc:roundtrip2".to_string(),
+            signature: Bytes {
+                bytes: b"round trip typed".to_vec(),
+            },
+            extra: HashMap::new(),
+        };
+
+        let typed = TypedLexicon::new(original.clone());
+
+        let json = serde_json::to_string(&typed).unwrap();
+        let deserialized: TypedSignature = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(deserialized.inner.issuer, original.issuer);
+        assert_eq!(deserialized.inner.signature.bytes, original.signature.bytes);
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_typed_signatures_vec() {
+        let typed_sigs: Vec<TypedSignature> = vec![
+            create_typed_signature(
+                "did:plc:first".to_string(),
+                Bytes {
+                    bytes: b"first".to_vec(),
+                },
+            ),
+            create_typed_signature(
+                "did:plc:second".to_string(),
+                Bytes {
+                    bytes: b"second".to_vec(),
+                },
+            ),
+        ];
+
+        let json = serde_json::to_value(&typed_sigs).unwrap();
+
+        assert!(json.is_array());
+        assert_eq!(json[0]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json[0]["issuer"], "did:plc:first");
+        assert_eq!(json[1]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json[1]["issuer"], "did:plc:second");
+    }
+
+    #[test]
+    fn test_plain_vs_typed_signature() {
+        // Plain Signature doesn't include $type field
+        let plain_sig = Signature {
+            issuer: "did:plc:plain".to_string(),
+            signature: Bytes {
+                bytes: b"plain sig".to_vec(),
+            },
+            extra: HashMap::new(),
+        };
+
+        let plain_json = serde_json::to_value(&plain_sig).unwrap();
+        assert!(!plain_json.as_object().unwrap().contains_key("$type"));
+
+        // TypedSignature automatically includes $type field
+        let typed_sig = TypedLexicon::new(plain_sig.clone());
+        let typed_json = serde_json::to_value(&typed_sig).unwrap();
+        assert_eq!(
+            typed_json["$type"],
+            "community.lexicon.attestation.signature"
+        );
+
+        // Both have the same core data
+        assert_eq!(plain_json["issuer"], typed_json["issuer"]);
+        assert_eq!(plain_json["signature"], typed_json["signature"]);
+    }
+
+    #[test]
+    fn test_signature_or_ref_inline() {
+        // Test inline signature
+        let inline_sig = create_typed_signature(
+            "did:plc:inline".to_string(),
+            Bytes {
+                bytes: b"inline signature".to_vec(),
+            },
+        );
+
+        let sig_or_ref = SignatureOrRef::Inline(inline_sig);
+
+        // Serialize
+        let json = serde_json::to_value(&sig_or_ref).unwrap();
+        assert_eq!(json["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(json["issuer"], "did:plc:inline");
+        assert_eq!(json["signature"]["$bytes"], "aW5saW5lIHNpZ25hdHVyZQ=="); // "inline signature" in base64
+
+        // Deserialize
+        let deserialized: SignatureOrRef = serde_json::from_value(json.clone()).unwrap();
+        match deserialized {
+            SignatureOrRef::Inline(sig) => {
+                assert_eq!(sig.inner.issuer, "did:plc:inline");
+                assert_eq!(sig.inner.signature.bytes, b"inline signature");
+            }
+            _ => panic!("Expected inline signature"),
+        }
+    }
+
+    #[test]
+    fn test_signature_or_ref_reference() {
+        // Test reference to signature
+        let strong_ref = StrongRef {
+            uri: "at://did:plc:repo/community.lexicon.attestation.signature/abc123".to_string(),
+            cid: "bafyreisigref123".to_string(),
+        };
+        let typed_ref = TypedLexicon::new(strong_ref);
+
+        let sig_or_ref = SignatureOrRef::Reference(typed_ref);
+
+        // Serialize
+        let json = serde_json::to_value(&sig_or_ref).unwrap();
+        assert_eq!(json["$type"], "com.atproto.repo.strongRef");
+        assert_eq!(
+            json["uri"],
+            "at://did:plc:repo/community.lexicon.attestation.signature/abc123"
+        );
+        assert_eq!(json["cid"], "bafyreisigref123");
+
+        // Deserialize
+        let deserialized: SignatureOrRef = serde_json::from_value(json.clone()).unwrap();
+        match deserialized {
+            SignatureOrRef::Reference(ref_) => {
+                assert_eq!(
+                    ref_.uri,
+                    "at://did:plc:repo/community.lexicon.attestation.signature/abc123"
+                );
+                assert_eq!(ref_.cid, "bafyreisigref123");
+            }
+            _ => panic!("Expected reference"),
+        }
+    }
+
+    #[test]
+    fn test_signatures_mixed_vector() {
+        // Create a vector with both inline and referenced signatures
+        let signatures: Signatures = vec![
+            // Inline signature
+            SignatureOrRef::Inline(create_typed_signature(
+                "did:plc:signer1".to_string(),
+                Bytes {
+                    bytes: b"sig1".to_vec(),
+                },
+            )),
+            // Referenced signature
+            SignatureOrRef::Reference(TypedLexicon::new(StrongRef {
+                uri: "at://did:plc:repo/community.lexicon.attestation.signature/sig2".to_string(),
+                cid: "bafyreisig2".to_string(),
+            })),
+            // Another inline signature
+            SignatureOrRef::Inline(create_typed_signature(
+                "did:plc:signer3".to_string(),
+                Bytes {
+                    bytes: b"sig3".to_vec(),
+                },
+            )),
+        ];
+
+        // Serialize
+        let json = serde_json::to_value(&signatures).unwrap();
+        assert!(json.is_array());
+        let array = json.as_array().unwrap();
+        assert_eq!(array.len(), 3);
+
+        // First element should be inline signature
+        assert_eq!(array[0]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(array[0]["issuer"], "did:plc:signer1");
+
+        // Second element should be reference
+        assert_eq!(array[1]["$type"], "com.atproto.repo.strongRef");
+        assert_eq!(
+            array[1]["uri"],
+            "at://did:plc:repo/community.lexicon.attestation.signature/sig2"
+        );
+
+        // Third element should be inline signature
+        assert_eq!(array[2]["$type"], "community.lexicon.attestation.signature");
+        assert_eq!(array[2]["issuer"], "did:plc:signer3");
+
+        // Deserialize back
+        let deserialized: Signatures = serde_json::from_value(json).unwrap();
+        assert_eq!(deserialized.len(), 3);
+
+        // Verify each element
+        match &deserialized[0] {
+            SignatureOrRef::Inline(sig) => assert_eq!(sig.inner.issuer, "did:plc:signer1"),
+            _ => panic!("Expected inline signature at index 0"),
+        }
+
+        match &deserialized[1] {
+            SignatureOrRef::Reference(ref_) => {
+                assert_eq!(
+                    ref_.uri,
+                    "at://did:plc:repo/community.lexicon.attestation.signature/sig2"
+                )
+            }
+            _ => panic!("Expected reference at index 1"),
+        }
+
+        match &deserialized[2] {
+            SignatureOrRef::Inline(sig) => assert_eq!(sig.inner.issuer, "did:plc:signer3"),
+            _ => panic!("Expected inline signature at index 2"),
+        }
+    }
+
+    #[test]
+    fn test_signature_or_ref_deserialization_from_json() {
+        // Test deserializing from raw JSON strings
+
+        // Inline signature JSON
+        let inline_json = r#"{
+            "$type": "community.lexicon.attestation.signature",
+            "issuer": "did:plc:testinline",
+            "signature": {"$bytes": "aGVsbG8="}
+        }"#;
+
+        let inline_deser: SignatureOrRef = serde_json::from_str(inline_json).unwrap();
+        match inline_deser {
+            SignatureOrRef::Inline(sig) => {
+                assert_eq!(sig.inner.issuer, "did:plc:testinline");
+                assert_eq!(sig.inner.signature.bytes, b"hello");
+            }
+            _ => panic!("Expected inline signature"),
+        }
+
+        // Reference JSON
+        let ref_json = r#"{
+            "$type": "com.atproto.repo.strongRef",
+            "uri": "at://did:plc:test/collection/record",
+            "cid": "bafyreicid"
+        }"#;
+
+        let ref_deser: SignatureOrRef = serde_json::from_str(ref_json).unwrap();
+        match ref_deser {
+            SignatureOrRef::Reference(ref_) => {
+                assert_eq!(ref_.uri, "at://did:plc:test/collection/record");
+                assert_eq!(ref_.cid, "bafyreicid");
+            }
+            _ => panic!("Expected reference"),
+        }
+    }
+}

crates/atproto-record/src/lexicon/community_lexicon_badge.rs

···
+//! Badge and award types for AT Protocol.
+//!
+//! This module provides types for badge definitions and awards in the AT Protocol.
+//! Badges can be defined with names, descriptions, and optional images, then awarded
+//! to users with cryptographic signatures for verification.
+
+use std::collections::HashMap;
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::lexicon::{
+    TypedBlob, com_atproto_repo::TypedStrongRef, community_lexicon_attestation::Signatures,
+};
+use crate::typed::{LexiconType, TypedLexicon};
+
+/// The namespace identifier for badge definitions
+pub const DEFINITION_NSID: &str = "community.lexicon.badge.definition";
+/// The namespace identifier for badge awards
+pub const AWARD_NSID: &str = "community.lexicon.badge.award";
+
+/// Badge definition structure.
+///
+/// Defines a badge that can be awarded to users. Badges have a name,
+/// description, and optional visual representation.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::badge::{Definition, TypedDefinition};
+/// use std::collections::HashMap;
+///
+/// let badge = Definition {
+///     name: "Early Adopter".to_string(),
+///     description: "Joined the platform in the first month".to_string(),
+///     image: None,
+///     extra: HashMap::new(),
+/// };
+///
+/// let typed_badge = TypedDefinition::new(badge);
+/// ```
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+pub struct Definition {
+    /// Name of the badge
+    pub name: String,
+    /// Description of what the badge represents
+    pub description: String,
+
+    /// Optional badge image
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub image: Option<TypedBlob>,
+
+    /// Extension fields for forward compatibility
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl LexiconType for Definition {
+    fn lexicon_type() -> &'static str {
+        DEFINITION_NSID
+    }
+}
+
+/// Type alias for Definition with automatic $type field handling
+pub type TypedDefinition = TypedLexicon<Definition>;
+
+/// Badge award structure.
+///
+/// Represents the awarding of a badge to a specific user (identified by DID).
+/// Awards include the badge reference, recipient, issue date, and optional
+/// signatures for verification.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::badge::{Award, TypedAward};
+/// use atproto_record::lexicon::com::atproto::repo::{StrongRef, TypedStrongRef};
+/// use chrono::Utc;
+/// use std::collections::HashMap;
+///
+/// let award = Award {
+///     badge: TypedStrongRef::new(StrongRef {
+///         uri: "at://did:plc:issuer/community.lexicon.badge.definition/badge123".to_string(),
+///         cid: "bafyreicid123".to_string(),
+///     }),
+///     did: "did:plc:recipient".to_string(),
+///     issued: Utc::now(),
+///     signatures: vec![],
+///     extra: HashMap::new(),
+/// };
+///
+/// let typed_award = TypedAward::new(award);
+/// ```
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+pub struct Award {
+    /// Reference to the badge definition being awarded
+    pub badge: TypedStrongRef,
+    /// DID of the recipient
+    pub did: String,
+    /// When the badge was awarded
+    pub issued: DateTime<Utc>,
+
+    /// Optional signatures for verification
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub signatures: Signatures,
+
+    /// Extension fields for forward compatibility
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl LexiconType for Award {
+    fn lexicon_type() -> &'static str {
+        AWARD_NSID
+    }
+}
+
+/// Type alias for Award with automatic $type field handling
+pub type TypedAward = TypedLexicon<Award>;
+
+#[cfg(test)]
+mod tests {
+    use crate::lexicon::com_atproto_repo::StrongRef;
+    use crate::lexicon::{Blob, Link};
+
+    use super::*;
+    use anyhow::Result;
+
+    #[test]
+    fn test_deserialize_badge_definition() -> Result<()> {
+        let json = r#"{
+            "name": "Bug Squasher",
+            "$type": "community.lexicon.badge.definition",
+            "image": {
+                "$type": "blob",
+                "ref": {
+                    "$link": "bafkreigb3vxlgckp66o2bffnwapagshpt2xdcgdltuzjymapobvgunxmfi"
+                },
+                "mimeType": "image/png",
+                "size": 177111
+            },
+            "description": "You've helped squash Smoke Signal bugs."
+        }"#;
+
+        let typed_def: TypedDefinition = serde_json::from_str(json)?;
+        let definition = typed_def.inner;
+
+        assert_eq!(definition.name, "Bug Squasher");
+        assert_eq!(
+            definition.description,
+            "You've helped squash Smoke Signal bugs."
+        );
+
+        assert!(definition.image.is_some());
+        if let Some(typed_blob) = definition.image {
+            // The blob is now wrapped in TypedBlob, so we access via .inner
+            let img = typed_blob.inner;
+            assert_eq!(img.mime_type, "image/png");
+            assert_eq!(img.size, 177111);
+            assert_eq!(
+                img.ref_.link,
+                "bafkreigb3vxlgckp66o2bffnwapagshpt2xdcgdltuzjymapobvgunxmfi"
+            );
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_deserialize_badge_definition_without_image() -> Result<()> {
+        let json = r#"{
+            "name": "Text Badge",
+            "$type": "community.lexicon.badge.definition",
+            "description": "A badge without an image."
+        }"#;
+
+        let typed_def: TypedDefinition = serde_json::from_str(json)?;
+        let definition = typed_def.inner;
+
+        assert_eq!(definition.name, "Text Badge");
+        assert_eq!(definition.description, "A badge without an image.");
+        assert!(definition.image.is_none());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_serialize_badge_definition() -> Result<()> {
+        let definition = Definition {
+            name: "Test Badge".to_string(),
+            description: "A test badge".to_string(),
+            image: Some(TypedLexicon::new(Blob {
+                ref_: Link {
+                    link: "bafkreitest123".to_string(),
+                },
+                mime_type: "image/png".to_string(),
+                size: 12345,
+            })),
+            extra: HashMap::new(),
+        };
+        let typed_def = TypedLexicon::new(definition);
+
+        let json = serde_json::to_string_pretty(&typed_def)?;
+
+        // Verify it contains the expected fields
+        assert!(json.contains("\"$type\": \"community.lexicon.badge.definition\""));
+        assert!(json.contains("\"name\": \"Test Badge\""));
+        assert!(json.contains("\"description\": \"A test badge\""));
+        assert!(json.contains("\"$link\": \"bafkreitest123\""));
+        assert!(json.contains("\"mimeType\": \"image/png\""));
+        assert!(json.contains("\"size\": 12345"));
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_deserialize_badge_award() -> Result<()> {
+        let json = r#"{
+            "$type": "community.lexicon.badge.award",
+            "badge": {
+                "$type": "com.atproto.repo.strongRef",
+                "cid": "bafyreiansi5jdnsam57ouyzk7zf5vatvzo7narb5o5z3zm7e5lhd4iw5d4",
+                "uri": "at://did:plc:tgudj2fjm77pzkuawquqhsxm/community.lexicon.badge.definition/3lqt67gc2i32c"
+            },
+            "did": "did:plc:cbkjy5n7bk3ax2wplmtjofq2",
+            "issued": "2025-06-08T22:10:55.000Z",
+            "signatures": []
+        }"#;
+
+        let typed_award: TypedAward = serde_json::from_str(json)?;
+        let award = typed_award.inner;
+
+        assert_eq!(award.did, "did:plc:cbkjy5n7bk3ax2wplmtjofq2");
+        assert_eq!(award.issued.to_rfc3339(), "2025-06-08T22:10:55+00:00");
+        assert!(award.signatures.is_empty());
+
+        // badge is a TypedStrongRef, so we access the inner StrongRef
+        let badge_ref = &award.badge.inner;
+        assert_eq!(
+            badge_ref.cid,
+            "bafyreiansi5jdnsam57ouyzk7zf5vatvzo7narb5o5z3zm7e5lhd4iw5d4"
+        );
+        assert_eq!(
+            badge_ref.uri,
+            "at://did:plc:tgudj2fjm77pzkuawquqhsxm/community.lexicon.badge.definition/3lqt67gc2i32c"
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_serialize_badge_award() -> Result<()> {
+        use chrono::TimeZone;
+
+        let badge_ref = StrongRef {
+            uri: "at://did:plc:test/community.lexicon.badge.definition/abc123".to_string(),
+            cid: "bafyreicidtest123".to_string(),
+        };
+        let award = Award {
+            badge: TypedLexicon::new(badge_ref),
+            did: "did:plc:recipient123".to_string(),
+            issued: Utc.with_ymd_and_hms(2025, 6, 8, 22, 10, 55).unwrap(),
+            signatures: vec![],
+            extra: HashMap::new(),
+        };
+        let typed_award = TypedLexicon::new(award);
+
+        let json = serde_json::to_string_pretty(&typed_award)?;
+
+        // Verify it contains the expected fields
+        assert!(json.contains("\"$type\": \"community.lexicon.badge.award\""));
+        assert!(json.contains("\"did\": \"did:plc:recipient123\""));
+        assert!(json.contains("\"issued\": \"2025-06-08T22:10:55Z\""));
+        assert!(json.contains("\"$type\": \"com.atproto.repo.strongRef\""));
+        // Empty signatures array is skipped in serialization due to skip_serializing_if
+        assert!(!json.contains("\"signatures\""));
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_badge_award_with_signatures() -> Result<()> {
+        let json = r#"{
+            "$type": "community.lexicon.badge.award",
+            "badge": {
+                "$type": "com.atproto.repo.strongRef",
+                "cid": "bafyreicid123",
+                "uri": "at://did:plc:issuer/community.lexicon.badge.definition/badge123"
+            },
+            "did": "did:plc:recipient",
+            "issued": "2025-06-08T12:00:00.000Z",
+            "signatures": [
+                {
+                    "$type": "community.lexicon.attestation.signature",
+                    "issuer": "did:plc:issuer",
+                    "signature": {"$bytes": "dGVzdCBzaWduYXR1cmU="}
+                }
+            ]
+        }"#;
+
+        let typed_award: TypedAward = serde_json::from_str(json)?;
+        let award = typed_award.inner;
+
+        assert_eq!(award.did, "did:plc:recipient");
+        assert_eq!(award.signatures.len(), 1);
+
+        match award.signatures.first() {
+            Some(sig_or_ref) => {
+                // The signature should be inline in this test
+                match sig_or_ref {
+                    crate::lexicon::community_lexicon_attestation::SignatureOrRef::Inline(sig) => {
+                        assert_eq!(sig.issuer, "did:plc:issuer");
+                        // The bytes should match the decoded base64 value
+                        // "dGVzdCBzaWduYXR1cmU=" decodes to "test signature"
+                        assert_eq!(sig.signature.bytes, b"test signature".to_vec());
+                    }
+                    _ => panic!("Expected inline signature"),
+                }
+            }
+            None => assert!(false),
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_patterns() -> Result<()> {
+        // Test that typed patterns automatically handle $type fields
+
+        // StrongRef without explicit $type field
+        let strong_ref = StrongRef {
+            uri: "at://example".to_string(),
+            cid: "bafytest".to_string(),
+        };
+        let typed_ref = TypedLexicon::new(strong_ref);
+        let json = serde_json::to_value(&typed_ref)?;
+        assert_eq!(json["$type"], "com.atproto.repo.strongRef");
+
+        // Definition without explicit $type field
+        let definition = Definition {
+            name: "Test".to_string(),
+            description: "Test desc".to_string(),
+            image: None,
+            extra: HashMap::new(),
+        };
+        let typed_def = TypedLexicon::new(definition);
+        let json = serde_json::to_value(&typed_def)?;
+        assert_eq!(json["$type"], "community.lexicon.badge.definition");
+
+        // Award without explicit $type field
+        let award = Award {
+            badge: typed_ref,
+            did: "did:plc:test".to_string(),
+            issued: Utc::now(),
+            signatures: vec![],
+            extra: HashMap::new(),
+        };
+        let typed_award = TypedLexicon::new(award);
+        let json = serde_json::to_value(&typed_award)?;
+        assert_eq!(json["$type"], "community.lexicon.badge.award");
+
+        Ok(())
+    }
+}

crates/atproto-record/src/lexicon/community_lexicon_calendar_event.rs

···
+//! Calendar event types for AT Protocol.
+//!
+//! This module provides types for representing calendar events with support
+//! for various event properties including status, mode (in-person/virtual/hybrid),
+//! locations, media, and links.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+use crate::datetime::format as datetime_format;
+use crate::datetime::optional_format as optional_datetime_format;
+use crate::lexicon::community::lexicon::location::Locations;
+use crate::lexicon::{Blob, TypedBlob};
+use crate::typed::{LexiconType, TypedLexicon};
+
+/// The namespace identifier for events
+pub const NSID: &str = "community.lexicon.calendar.event";
+
+/// Event status enumeration.
+///
+/// Represents the current status of a calendar event.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, Default)]
+pub enum Status {
+    /// Event is scheduled and confirmed
+    #[default]
+    #[serde(rename = "community.lexicon.calendar.event#scheduled")]
+    Scheduled,
+
+    /// Event has been rescheduled to a new time
+    #[serde(rename = "community.lexicon.calendar.event#rescheduled")]
+    Rescheduled,
+
+    /// Event has been cancelled
+    #[serde(rename = "community.lexicon.calendar.event#cancelled")]
+    Cancelled,
+
+    /// Event has been postponed (new date TBD)
+    #[serde(rename = "community.lexicon.calendar.event#postponed")]
+    Postponed,
+
+    /// Event is being planned but not yet confirmed
+    #[serde(rename = "community.lexicon.calendar.event#planned")]
+    Planned,
+}
+
+/// Event mode enumeration.
+///
+/// Represents how attendees can participate in the event.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, Default)]
+pub enum Mode {
+    /// In-person attendance only
+    #[default]
+    #[serde(rename = "community.lexicon.calendar.event#inperson")]
+    InPerson,
+
+    /// Virtual/online attendance only
+    #[serde(rename = "community.lexicon.calendar.event#virtual")]
+    Virtual,
+
+    /// Both in-person and virtual attendance options
+    #[serde(rename = "community.lexicon.calendar.event#hybrid")]
+    Hybrid,
+}
+
+/// The namespace identifier for named URIs
+pub const NAMED_URI_NSID: &str = "community.lexicon.calendar.event#uri";
+
+/// Named URI structure.
+///
+/// Represents a URI with an optional human-readable name.
+/// Used for linking to external resources related to an event.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct NamedUri {
+    /// The URI/URL
+    pub uri: String,
+
+    /// Optional human-readable name for the link
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for NamedUri {
+    fn lexicon_type() -> &'static str {
+        NAMED_URI_NSID
+    }
+}
+
+/// Type alias for NamedUri with automatic $type field handling
+pub type TypedNamedUri = TypedLexicon<NamedUri>;
+
+/// The namespace identifier for event links
+pub const EVENT_LINK_NSID: &str = "community.lexicon.calendar.event#uri";
+
+/// Event link structure.
+///
+/// Similar to NamedUri but kept as a separate type for semantic clarity
+/// and type safety when dealing with event-specific links.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct EventLink {
+    /// The URI/URL for the event link
+    pub uri: String,
+
+    /// Optional human-readable name for the link
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for EventLink {
+    fn lexicon_type() -> &'static str {
+        EVENT_LINK_NSID
+    }
+}
+
+/// Type alias for EventLink with automatic $type field handling
+pub type TypedEventLink = TypedLexicon<EventLink>;
+
+/// A vector of typed event links
+pub type EventLinks = Vec<TypedEventLink>;
+
+/// Aspect ratio for media content.
+///
+/// Represents the width-to-height ratio of visual media.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct AspectRatio {
+    /// Width component of the ratio
+    pub width: u64,
+    /// Height component of the ratio
+    pub height: u64,
+}
+
+/// The namespace identifier for media
+pub const MEDIA_NSID: &str = "community.lexicon.calendar.event#media";
+
+/// Media structure for event-related visual content.
+///
+/// Represents images, videos, or other media associated with an event.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Media {
+    /// The media content as a blob reference
+    pub content: TypedBlob,
+
+    /// Alternative text description for accessibility
+    pub alt: String,
+
+    /// The role/purpose of this media (e.g., "banner", "poster", "thumbnail")
+    pub role: String,
+
+    /// Optional aspect ratio information
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub aspect_ratio: Option<AspectRatio>,
+}
+
+impl LexiconType for Media {
+    fn lexicon_type() -> &'static str {
+        MEDIA_NSID
+    }
+}
+
+/// Type alias for Media with automatic $type field handling
+pub type TypedMedia = TypedLexicon<Media>;
+
+/// A vector of typed media items
+pub type MediaList = Vec<TypedMedia>;
+
+/// Calendar event structure.
+///
+/// Represents a calendar event with comprehensive metadata including
+/// timing, location, media, and status information.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::calendar::event::{Event, TypedEvent, Status, Mode};
+/// use chrono::Utc;
+/// use std::collections::HashMap;
+///
+/// let event = Event {
+///     name: "Community Meetup".to_string(),
+///     description: "Monthly community gathering".to_string(),
+///     created_at: Utc::now(),
+///     starts_at: Some(Utc::now()),
+///     ends_at: None,
+///     mode: Some(Mode::Hybrid),
+///     status: Some(Status::Scheduled),
+///     locations: vec![],
+///     uris: vec![],
+///     media: vec![],
+///     extra: HashMap::new(),
+/// };
+///
+/// let typed_event = TypedEvent::new(event);
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Event {
+    /// Name/title of the event
+    pub name: String,
+
+    /// Description of the event
+    pub description: String,
+
+    /// When the event record was created
+    #[serde(rename = "createdAt", with = "datetime_format")]
+    pub created_at: DateTime<Utc>,
+
+    /// When the event starts (optional)
+    #[serde(
+        rename = "startsAt",
+        skip_serializing_if = "Option::is_none",
+        default,
+        with = "optional_datetime_format"
+    )]
+    pub starts_at: Option<DateTime<Utc>>,
+
+    /// When the event ends (optional)
+    #[serde(
+        rename = "endsAt",
+        skip_serializing_if = "Option::is_none",
+        default,
+        with = "optional_datetime_format"
+    )]
+    pub ends_at: Option<DateTime<Utc>>,
+
+    /// Event mode (in-person, virtual, hybrid)
+    #[serde(rename = "mode", skip_serializing_if = "Option::is_none", default)]
+    pub mode: Option<Mode>,
+
+    /// Event status (scheduled, cancelled, etc.)
+    #[serde(rename = "status", skip_serializing_if = "Option::is_none", default)]
+    pub status: Option<Status>,
+
+    /// Event locations (can be inline or referenced)
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub locations: Locations,
+
+    /// Related URIs/links for the event
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub uris: EventLinks,
+
+    /// Media associated with the event
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub media: MediaList,
+
+    /// Extension fields for forward compatibility.
+    /// This catch-all allows unknown fields to be preserved and indexed
+    /// for potential future use without requiring re-indexing.
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl LexiconType for Event {
+    fn lexicon_type() -> &'static str {
+        NSID
+    }
+}
+
+/// Type alias for Event with automatic $type field handling.
+///
+/// This wrapper ensures proper serialization/deserialization of the
+/// `$type` field for event records.
+pub type TypedEvent = TypedLexicon<Event>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use anyhow::Result;
+
+    #[test]
+    fn test_typed_named_uri() -> Result<()> {
+        let test_json = r#"{"$type":"community.lexicon.calendar.event#uri","uri":"https://smokesignal.events/","name":"Smoke Signal"}"#;
+
+        // Serialize bare NamedUri
+        let named_uri = NamedUri {
+            uri: "https://smokesignal.events/".to_string(),
+            name: Some("Smoke Signal".to_string()),
+        };
+        let typed_uri = TypedLexicon::new(named_uri);
+        let serialized = serde_json::to_value(&typed_uri)?;
+        let expected: serde_json::Value = serde_json::from_str(test_json)?;
+        assert_eq!(serialized, expected);
+
+        // Deserialize bare NamedUri
+        let deserialized: TypedNamedUri = serde_json::from_str(test_json).unwrap();
+        assert_eq!(deserialized.inner.uri, "https://smokesignal.events/");
+        assert_eq!(deserialized.inner.name, Some("Smoke Signal".to_string()));
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_event() -> Result<()> {
+        use chrono::TimeZone;
+
+        // Create an Event without explicit $type field
+        let event = Event {
+            name: "Test Event".to_string(),
+            description: "A test event".to_string(),
+            created_at: Utc.with_ymd_and_hms(2025, 1, 1, 12, 0, 0).unwrap(),
+            starts_at: Some(Utc.with_ymd_and_hms(2025, 1, 15, 14, 0, 0).unwrap()),
+            ends_at: Some(Utc.with_ymd_and_hms(2025, 1, 15, 16, 0, 0).unwrap()),
+            mode: Some(Mode::Hybrid),
+            status: Some(Status::Scheduled),
+            locations: vec![],
+            uris: vec![],
+            media: vec![],
+            extra: HashMap::new(),
+        };
+
+        // Wrap it in TypedEvent
+        let typed_event = TypedLexicon::new(event.clone());
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_event)?;
+        assert_eq!(json["$type"], "community.lexicon.calendar.event");
+        assert_eq!(json["name"], "Test Event");
+        assert_eq!(json["description"], "A test event");
+
+        // Deserialize with $type field
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.event",
+            "name": "Deserialized Event",
+            "description": "Event from JSON",
+            "createdAt": "2025-01-01T12:00:00Z",
+            "startsAt": "2025-01-15T14:00:00Z",
+            "endsAt": "2025-01-15T16:00:00Z",
+            "mode": "community.lexicon.calendar.event#hybrid",
+            "status": "community.lexicon.calendar.event#scheduled"
+        }"#;
+
+        let deserialized: TypedEvent = serde_json::from_str(json_str)?;
+        assert_eq!(deserialized.inner.name, "Deserialized Event");
+        assert_eq!(deserialized.inner.description, "Event from JSON");
+        assert!(deserialized.has_type_field());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_event_link() -> Result<()> {
+        // Create an EventLink without explicit $type field
+        let event_link = EventLink {
+            uri: "https://example.com/event".to_string(),
+            name: Some("Example Event".to_string()),
+        };
+
+        // Wrap it in TypedEventLink
+        let typed_link = TypedLexicon::new(event_link);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_link)?;
+        assert_eq!(json["$type"], "community.lexicon.calendar.event#uri");
+        assert_eq!(json["uri"], "https://example.com/event");
+        assert_eq!(json["name"], "Example Event");
+
+        // Deserialize with $type field
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.event#uri",
+            "uri": "https://test.com",
+            "name": "Test Link"
+        }"#;
+
+        let deserialized: TypedEventLink = serde_json::from_str(json_str)?;
+        assert_eq!(deserialized.inner.uri, "https://test.com");
+        assert_eq!(deserialized.inner.name, Some("Test Link".to_string()));
+        assert!(deserialized.has_type_field());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_media() -> Result<()> {
+        // Create a Media without explicit $type field
+        let media = Media {
+            content: TypedLexicon::new(Blob {
+                ref_: crate::lexicon::Link {
+                    link: "bafkreiblob123".to_string(),
+                },
+                mime_type: "image/jpeg".to_string(),
+                size: 12345,
+            }),
+            alt: "Test image".to_string(),
+            role: "banner".to_string(),
+            aspect_ratio: Some(AspectRatio {
+                width: 1920,
+                height: 1080,
+            }),
+        };
+
+        // Wrap it in TypedMedia
+        let typed_media = TypedLexicon::new(media);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_media)?;
+        assert_eq!(json["$type"], "community.lexicon.calendar.event#media");
+        assert_eq!(json["alt"], "Test image");
+        assert_eq!(json["role"], "banner");
+        assert_eq!(json["content"]["$type"], "blob");
+        assert_eq!(json["aspect_ratio"]["width"], 1920);
+        assert_eq!(json["aspect_ratio"]["height"], 1080);
+
+        // Deserialize with $type field
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.event#media",
+            "content": {
+                "$type": "blob",
+                "ref": {
+                    "$link": "bafkreitest456"
+                },
+                "mimeType": "image/png",
+                "size": 54321
+            },
+            "alt": "Another test",
+            "role": "thumbnail"
+        }"#;
+
+        let deserialized: TypedMedia = serde_json::from_str(json_str)?;
+        assert_eq!(deserialized.inner.alt, "Another test");
+        assert_eq!(deserialized.inner.role, "thumbnail");
+        assert_eq!(deserialized.inner.content.inner.mime_type, "image/png");
+        assert!(deserialized.inner.aspect_ratio.is_none());
+        assert!(deserialized.has_type_field());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_event_with_typed_fields() -> Result<()> {
+        use chrono::TimeZone;
+
+        // Create an Event with typed fields
+        let event_link = EventLink {
+            uri: "https://event.com".to_string(),
+            name: Some("Event Website".to_string()),
+        };
+
+        let media = Media {
+            content: TypedLexicon::new(Blob {
+                ref_: crate::lexicon::Link {
+                    link: "bafkreimedia".to_string(),
+                },
+                mime_type: "image/jpeg".to_string(),
+                size: 99999,
+            }),
+            alt: "Event poster".to_string(),
+            role: "poster".to_string(),
+            aspect_ratio: None,
+        };
+
+        let event = Event {
+            name: "Complex Event".to_string(),
+            description: "Event with typed fields".to_string(),
+            created_at: Utc.with_ymd_and_hms(2025, 1, 1, 12, 0, 0).unwrap(),
+            starts_at: None,
+            ends_at: None,
+            mode: None,
+            status: None,
+            locations: vec![],
+            uris: vec![TypedLexicon::new(event_link)],
+            media: vec![TypedLexicon::new(media)],
+            extra: HashMap::new(),
+        };
+
+        // Wrap it in TypedEvent
+        let typed_event = TypedLexicon::new(event);
+
+        // Serialize and verify nested types have their $type fields
+        let json = serde_json::to_value(&typed_event)?;
+        assert_eq!(json["$type"], "community.lexicon.calendar.event");
+        assert_eq!(json["name"], "Complex Event");
+
+        // Check nested EventLink has $type
+        assert_eq!(
+            json["uris"][0]["$type"],
+            "community.lexicon.calendar.event#uri"
+        );
+        assert_eq!(json["uris"][0]["uri"], "https://event.com");
+
+        // Check nested Media has $type
+        assert_eq!(
+            json["media"][0]["$type"],
+            "community.lexicon.calendar.event#media"
+        );
+        assert_eq!(json["media"][0]["alt"], "Event poster");
+
+        Ok(())
+    }
+}

crates/atproto-record/src/lexicon/community_lexicon_calendar_rsvp.rs

···
+//! RSVP types for calendar events in AT Protocol.
+//!
+//! This module provides types for representing RSVPs (responses) to calendar
+//! events, including status indicators and signature support for verification.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+use crate::datetime::format as datetime_format;
+use crate::lexicon::com::atproto::repo::StrongRef;
+use crate::lexicon::community_lexicon_attestation::Signatures;
+use crate::typed::{LexiconType, TypedLexicon};
+
+/// The namespace identifier for RSVPs
+pub const NSID: &str = "community.lexicon.calendar.rsvp";
+
+/// RSVP status enumeration.
+///
+/// Represents the response status for an event invitation.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, Default)]
+pub enum RsvpStatus {
+    /// Attendee is planning to attend
+    #[default]
+    #[serde(rename = "community.lexicon.calendar.rsvp#going")]
+    Going,
+
+    /// Attendee is interested but not confirmed
+    #[serde(rename = "community.lexicon.calendar.rsvp#interested")]
+    Interested,
+
+    /// Attendee is not planning to attend
+    #[serde(rename = "community.lexicon.calendar.rsvp#notgoing")]
+    NotGoing,
+}
+
+/// RSVP record structure.
+///
+/// Represents a user's response to an event invitation, including their
+/// attendance status and optional signatures for verification.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::calendar::rsvp::{Rsvp, TypedRsvp, RsvpStatus};
+/// use atproto_record::lexicon::com::atproto::repo::StrongRef;
+/// use chrono::Utc;
+/// use std::collections::HashMap;
+///
+/// let rsvp = Rsvp {
+///     subject: StrongRef {
+///         uri: "at://did:plc:example/community.lexicon.calendar.event/abc123".to_string(),
+///         cid: "bafyreicid123".to_string(),
+///     },
+///     status: RsvpStatus::Going,
+///     created_at: Utc::now(),
+///     signatures: vec![],
+///     extra: HashMap::new(),
+/// };
+///
+/// // Use TypedRsvp for automatic $type field handling
+/// let typed_rsvp = TypedRsvp::new(rsvp);
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Rsvp {
+    /// Reference to the event being responded to
+    pub subject: StrongRef,
+
+    /// The RSVP status (going, interested, not going)
+    pub status: RsvpStatus,
+
+    /// When this RSVP was created
+    #[serde(rename = "createdAt", with = "datetime_format")]
+    pub created_at: DateTime<Utc>,
+
+    /// Optional signatures for verification
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub signatures: Signatures,
+
+    /// Extension fields for forward compatibility
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl LexiconType for Rsvp {
+    fn lexicon_type() -> &'static str {
+        NSID
+    }
+}
+
+/// Type alias for Rsvp with automatic $type field handling.
+///
+/// This wrapper ensures that the `$type` field is automatically
+/// added during serialization and validated during deserialization.
+pub type TypedRsvp = TypedLexicon<Rsvp>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use anyhow::Result;
+    use chrono::TimeZone;
+
+    #[test]
+    fn test_typed_rsvp_serialization() -> Result<()> {
+        // Create an RSVP without explicit $type field
+        let rsvp = Rsvp {
+            subject: StrongRef {
+                uri: "at://did:plc:example/community.lexicon.calendar.event/event123".to_string(),
+                cid: "bafyreievent123".to_string(),
+            },
+            status: RsvpStatus::Going,
+            created_at: Utc.with_ymd_and_hms(2025, 1, 15, 14, 0, 0).unwrap(),
+            signatures: vec![],
+            extra: HashMap::new(),
+        };
+
+        // Wrap it in TypedRsvp
+        let typed_rsvp = TypedLexicon::new(rsvp);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_rsvp)?;
+        assert_eq!(json["$type"], "community.lexicon.calendar.rsvp");
+        assert_eq!(
+            json["subject"]["uri"],
+            "at://did:plc:example/community.lexicon.calendar.event/event123"
+        );
+        assert_eq!(json["subject"]["cid"], "bafyreievent123");
+        assert_eq!(json["status"], "community.lexicon.calendar.rsvp#going");
+        assert_eq!(json["createdAt"], "2025-01-15T14:00:00.000Z");
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_rsvp_deserialization() -> Result<()> {
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.rsvp",
+            "subject": {
+                "uri": "at://did:plc:test/community.lexicon.calendar.event/abc",
+                "cid": "bafyreicid456"
+            },
+            "status": "community.lexicon.calendar.rsvp#interested",
+            "createdAt": "2025-01-10T10:00:00Z",
+            "signatures": []
+        }"#;
+
+        let typed_rsvp: TypedRsvp = serde_json::from_str(json_str)?;
+
+        assert_eq!(
+            typed_rsvp.inner.subject.uri,
+            "at://did:plc:test/community.lexicon.calendar.event/abc"
+        );
+        assert_eq!(typed_rsvp.inner.subject.cid, "bafyreicid456");
+        assert_eq!(typed_rsvp.inner.status, RsvpStatus::Interested);
+        assert!(typed_rsvp.has_type_field());
+        assert!(typed_rsvp.validate().is_ok());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_rsvp_without_type_field() -> Result<()> {
+        // Test that we can deserialize an RSVP without $type field
+        let json_str = r#"{
+            "subject": {
+                "uri": "at://did:plc:test/community.lexicon.calendar.event/xyz",
+                "cid": "bafyreicid789"
+            },
+            "status": "community.lexicon.calendar.rsvp#notgoing",
+            "createdAt": "2025-01-05T15:30:00Z",
+            "signatures": []
+        }"#;
+
+        let typed_rsvp: TypedRsvp = serde_json::from_str(json_str)?;
+
+        assert_eq!(
+            typed_rsvp.inner.subject.uri,
+            "at://did:plc:test/community.lexicon.calendar.event/xyz"
+        );
+        assert_eq!(typed_rsvp.inner.status, RsvpStatus::NotGoing);
+        assert!(!typed_rsvp.has_type_field());
+
+        // Validation should fail because type is required by default
+        assert!(typed_rsvp.validate().is_err());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_rsvp_status_serialization() -> Result<()> {
+        // Test all RSVP status values
+        let statuses = vec![
+            (RsvpStatus::Going, "community.lexicon.calendar.rsvp#going"),
+            (
+                RsvpStatus::Interested,
+                "community.lexicon.calendar.rsvp#interested",
+            ),
+            (
+                RsvpStatus::NotGoing,
+                "community.lexicon.calendar.rsvp#notgoing",
+            ),
+        ];
+
+        for (status, expected) in statuses {
+            let json = serde_json::to_value(&status)?;
+            assert_eq!(json, expected);
+
+            let deserialized: RsvpStatus = serde_json::from_value(json)?;
+            assert_eq!(deserialized, status);
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_typed_rsvp_round_trip() -> Result<()> {
+        let original = Rsvp {
+            subject: StrongRef {
+                uri: "at://did:plc:roundtrip/community.lexicon.calendar.event/test".to_string(),
+                cid: "bafyreiroundtrip".to_string(),
+            },
+            status: RsvpStatus::Going,
+            created_at: Utc.with_ymd_and_hms(2025, 2, 1, 12, 0, 0).unwrap(),
+            signatures: vec![],
+            extra: HashMap::new(),
+        };
+
+        let typed = TypedLexicon::new(original.clone());
+
+        let json = serde_json::to_string(&typed)?;
+        let deserialized: TypedRsvp = serde_json::from_str(&json)?;
+
+        assert_eq!(deserialized.inner.subject.uri, original.subject.uri);
+        assert_eq!(deserialized.inner.subject.cid, original.subject.cid);
+        assert_eq!(deserialized.inner.status, original.status);
+        assert_eq!(deserialized.inner.created_at, original.created_at);
+        assert!(deserialized.has_type_field());
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_rsvp_with_extra_fields() -> Result<()> {
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.rsvp",
+            "subject": {
+                "uri": "at://did:plc:test/community.lexicon.calendar.event/extra",
+                "cid": "bafyreiextra"
+            },
+            "status": "community.lexicon.calendar.rsvp#going",
+            "createdAt": "2025-01-20T09:00:00Z",
+            "signatures": [],
+            "customField": "customValue",
+            "anotherField": 42
+        }"#;
+
+        let typed_rsvp: TypedRsvp = serde_json::from_str(json_str)?;
+
+        assert_eq!(typed_rsvp.inner.extra.len(), 2);
+        assert_eq!(
+            typed_rsvp.inner.extra.get("customField").unwrap(),
+            "customValue"
+        );
+        assert_eq!(typed_rsvp.inner.extra.get("anotherField").unwrap(), 42);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_rsvp_with_signatures() -> Result<()> {
+        use crate::lexicon::community_lexicon_attestation::SignatureOrRef;
+
+        let json_str = r#"{
+            "$type": "community.lexicon.calendar.rsvp",
+            "subject": {
+                "uri": "at://did:plc:test/community.lexicon.calendar.event/signed",
+                "cid": "bafyreisigned"
+            },
+            "status": "community.lexicon.calendar.rsvp#going",
+            "createdAt": "2025-01-25T16:00:00Z",
+            "signatures": [
+                {
+                    "$type": "community.lexicon.attestation.signature",
+                    "issuer": "did:plc:issuer",
+                    "signature": {"$bytes": "dGVzdCBzaWduYXR1cmU="}
+                }
+            ]
+        }"#;
+
+        let typed_rsvp: TypedRsvp = serde_json::from_str(json_str)?;
+
+        assert_eq!(typed_rsvp.inner.signatures.len(), 1);
+        match &typed_rsvp.inner.signatures[0] {
+            SignatureOrRef::Inline(sig) => {
+                assert_eq!(sig.inner.issuer, "did:plc:issuer");
+                assert_eq!(sig.inner.signature.bytes, b"test signature");
+            }
+            _ => panic!("Expected inline signature"),
+        }
+
+        Ok(())
+    }
+}

crates/atproto-record/src/lexicon/community_lexicon_location.rs

···
+//! Location types for AT Protocol.
+//!
+//! This module provides various location representation types including
+//! addresses, geographic coordinates, Foursquare places, and H3 hexagonal
+//! hierarchical spatial indices.
+
+use crate::{
+    lexicon::com::atproto::repo::TypedStrongRef,
+    typed::{LexiconType, TypedLexicon},
+};
+use serde::{Deserialize, Serialize};
+
+/// Base namespace identifier for location types
+pub const NSID: &str = "community.lexicon.location";
+/// Namespace identifier for address locations
+pub const ADDRESS_NSID: &str = "community.lexicon.location.address";
+/// Namespace identifier for geographic coordinate locations
+pub const GEO_NSID: &str = "community.lexicon.location.geo";
+/// Namespace identifier for Foursquare locations
+pub const FSQ_NSID: &str = "community.lexicon.location.fsq";
+/// Namespace identifier for H3 locations
+pub const HTHREE_NSID: &str = "community.lexicon.location.hthree";
+
+/// Enum that can hold either a location reference or inline location data.
+///
+/// This type allows locations to be either embedded directly in a record
+/// or referenced via a strong reference. Supports multiple location types
+/// including addresses, coordinates, and third-party location identifiers.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::location::{LocationOrRef, TypedAddress, Address};
+///
+/// // Inline address
+/// let address = Address {
+///     country: "USA".to_string(),
+///     postal_code: Some("12345".to_string()),
+///     region: Some("CA".to_string()),
+///     locality: Some("San Francisco".to_string()),
+///     street: None,
+///     name: None,
+/// };
+/// let location = LocationOrRef::InlineAddress(TypedAddress::new(address));
+/// ```
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+#[serde(untagged)]
+pub enum LocationOrRef {
+    /// A reference to a location stored elsewhere
+    Reference(TypedStrongRef),
+    /// An inline address location
+    InlineAddress(TypedAddress),
+    /// An inline geographic coordinate location
+    InlineGeo(TypedGeo),
+    /// An inline H3 location
+    InlineHthree(TypedHthree),
+    /// An inline Foursquare location
+    InlineFsq(TypedFsq),
+}
+
+/// A vector of locations that can be either inline or referenced.
+///
+/// This type alias is commonly used in records that support multiple
+/// locations, such as events that might have both physical and virtual locations.
+pub type Locations = Vec<LocationOrRef>;
+
+/// Address location structure.
+///
+/// Represents a physical address with varying levels of detail.
+/// Only the country field is required; all other fields are optional.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::location::Address;
+///
+/// let address = Address {
+///     country: "United States".to_string(),
+///     postal_code: Some("94102".to_string()),
+///     region: Some("California".to_string()),
+///     locality: Some("San Francisco".to_string()),
+///     street: Some("123 Market St".to_string()),
+///     name: Some("Tech Hub Building".to_string()),
+/// };
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Address {
+    /// Country name (required)
+    pub country: String,
+
+    /// Postal/ZIP code
+    #[serde(
+        rename = "postalCode",
+        skip_serializing_if = "Option::is_none",
+        default
+    )]
+    pub postal_code: Option<String>,
+
+    /// State, province, or region
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub region: Option<String>,
+
+    /// City or locality
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub locality: Option<String>,
+
+    /// Street address
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub street: Option<String>,
+
+    /// Location name (e.g., building or venue name)
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for Address {
+    fn lexicon_type() -> &'static str {
+        ADDRESS_NSID
+    }
+}
+
+/// Type alias for Address with automatic $type field handling
+pub type TypedAddress = TypedLexicon<Address>;
+
+/// Geographic coordinates location structure.
+///
+/// Represents a location using latitude and longitude coordinates.
+/// Coordinates are stored as strings to preserve precision.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::location::Geo;
+///
+/// let location = Geo {
+///     latitude: "37.7749".to_string(),
+///     longitude: "-122.4194".to_string(),
+///     name: Some("San Francisco".to_string()),
+/// };
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Geo {
+    /// Latitude coordinate as a string
+    pub latitude: String,
+
+    /// Longitude coordinate as a string
+    pub longitude: String,
+
+    /// Optional human-readable name for this location
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for Geo {
+    fn lexicon_type() -> &'static str {
+        GEO_NSID
+    }
+}
+
+/// Type alias for Geo with automatic $type field handling
+pub type TypedGeo = TypedLexicon<Geo>;
+
+/// Foursquare location structure.
+///
+/// Represents a location using Foursquare's place identifier system.
+/// This allows integration with Foursquare's venue database.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::location::Fsq;
+///
+/// let location = Fsq {
+///     fsq_place_id: "4a27f3d4f964a520a4891fe3".to_string(),
+///     name: Some("Empire State Building".to_string()),
+/// };
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Fsq {
+    /// Foursquare place identifier
+    pub fsq_place_id: String,
+
+    /// Optional venue name from Foursquare
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for Fsq {
+    fn lexicon_type() -> &'static str {
+        FSQ_NSID
+    }
+}
+
+/// Type alias for Fsq with automatic $type field handling
+pub type TypedFsq = TypedLexicon<Fsq>;
+
+/// H3 location structure.
+///
+/// Represents a location using Uber's H3 hexagonal hierarchical spatial index.
+/// H3 provides a way to represent geographic areas as hexagons at various resolutions.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::community::lexicon::location::Hthree;
+///
+/// let location = Hthree {
+///     value: "8a2a1072b59ffff".to_string(),
+///     name: Some("Downtown Area".to_string()),
+/// };
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Hthree {
+    /// H3 hexagon identifier
+    pub value: String,
+
+    /// Optional human-readable name for this area
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub name: Option<String>,
+}
+
+impl LexiconType for Hthree {
+    fn lexicon_type() -> &'static str {
+        HTHREE_NSID
+    }
+}
+
+/// Type alias for Hthree with automatic $type field handling
+pub type TypedHthree = TypedLexicon<Hthree>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_typed_address() {
+        // Create an Address without explicit $type field
+        let address = Address {
+            country: "USA".to_string(),
+            postal_code: Some("12345".to_string()),
+            region: Some("California".to_string()),
+            locality: Some("San Francisco".to_string()),
+            street: Some("123 Main St".to_string()),
+            name: Some("Office Building".to_string()),
+        };
+
+        // Wrap it in TypedAddress
+        let typed_address = TypedLexicon::new(address.clone());
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_address).unwrap();
+        assert_eq!(json["$type"], "community.lexicon.location.address");
+        assert_eq!(json["country"], "USA");
+        assert_eq!(json["postalCode"], "12345");
+        assert_eq!(json["region"], "California");
+
+        // Deserialize with $type field
+        let json_str = r#"{
+            "$type": "community.lexicon.location.address",
+            "country": "Canada",
+            "postalCode": "K1A 0B1",
+            "region": "Ontario",
+            "locality": "Ottawa"
+        }"#;
+
+        let deserialized: TypedAddress = serde_json::from_str(json_str).unwrap();
+        assert_eq!(deserialized.inner.country, "Canada");
+        assert_eq!(deserialized.inner.postal_code, Some("K1A 0B1".to_string()));
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_typed_geo() {
+        // Create a Geo without explicit $type field
+        let geo = Geo {
+            latitude: "37.7749".to_string(),
+            longitude: "-122.4194".to_string(),
+            name: Some("San Francisco".to_string()),
+        };
+
+        // Wrap it in TypedGeo
+        let typed_geo = TypedLexicon::new(geo);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_geo).unwrap();
+        assert_eq!(json["$type"], "community.lexicon.location.geo");
+        assert_eq!(json["latitude"], "37.7749");
+        assert_eq!(json["longitude"], "-122.4194");
+        assert_eq!(json["name"], "San Francisco");
+
+        // Deserialize with $type field
+        let json_str = r#"{
+            "$type": "community.lexicon.location.geo",
+            "latitude": "40.7128",
+            "longitude": "-74.0060",
+            "name": "New York"
+        }"#;
+
+        let deserialized: TypedGeo = serde_json::from_str(json_str).unwrap();
+        assert_eq!(deserialized.inner.latitude, "40.7128");
+        assert_eq!(deserialized.inner.longitude, "-74.0060");
+        assert_eq!(deserialized.inner.name, Some("New York".to_string()));
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_typed_fsq() {
+        // Create an Fsq without explicit $type field
+        let fsq = Fsq {
+            fsq_place_id: "4a27f3d4f964a520a4891fe3".to_string(),
+            name: Some("Empire State Building".to_string()),
+        };
+
+        // Wrap it in TypedFsq
+        let typed_fsq = TypedLexicon::new(fsq);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_fsq).unwrap();
+        assert_eq!(json["$type"], "community.lexicon.location.fsq");
+        assert_eq!(json["fsq_place_id"], "4a27f3d4f964a520a4891fe3");
+        assert_eq!(json["name"], "Empire State Building");
+
+        // Deserialize without name field
+        let json_str = r#"{
+            "$type": "community.lexicon.location.fsq",
+            "fsq_place_id": "5642aef9498e51025cf4a7a5"
+        }"#;
+
+        let deserialized: TypedFsq = serde_json::from_str(json_str).unwrap();
+        assert_eq!(deserialized.inner.fsq_place_id, "5642aef9498e51025cf4a7a5");
+        assert_eq!(deserialized.inner.name, None);
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_typed_hthree() {
+        // Create an Hthree without explicit $type field
+        let hthree = Hthree {
+            value: "8a2a1072b59ffff".to_string(),
+            name: Some("Downtown Area".to_string()),
+        };
+
+        // Wrap it in TypedHthree
+        let typed_hthree = TypedLexicon::new(hthree);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_hthree).unwrap();
+        assert_eq!(json["$type"], "community.lexicon.location.hthree");
+        assert_eq!(json["value"], "8a2a1072b59ffff");
+        assert_eq!(json["name"], "Downtown Area");
+
+        // Deserialize without name field
+        let json_str = r#"{
+            "$type": "community.lexicon.location.hthree",
+            "value": "8928308280fffff"
+        }"#;
+
+        let deserialized: TypedHthree = serde_json::from_str(json_str).unwrap();
+        assert_eq!(deserialized.inner.value, "8928308280fffff");
+        assert_eq!(deserialized.inner.name, None);
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_optional_fields() {
+        // Test Address with minimal fields
+        let address = Address {
+            country: "USA".to_string(),
+            postal_code: None,
+            region: None,
+            locality: None,
+            street: None,
+            name: None,
+        };
+
+        let typed_address = TypedLexicon::new(address);
+        let json = serde_json::to_value(&typed_address).unwrap();
+
+        // Optional fields should not be present when None
+        assert_eq!(json["$type"], "community.lexicon.location.address");
+        assert_eq!(json["country"], "USA");
+        assert!(!json.as_object().unwrap().contains_key("postalCode"));
+        assert!(!json.as_object().unwrap().contains_key("region"));
+        assert!(!json.as_object().unwrap().contains_key("locality"));
+        assert!(!json.as_object().unwrap().contains_key("street"));
+        assert!(!json.as_object().unwrap().contains_key("name"));
+
+        // Test Geo with minimal fields
+        let geo = Geo {
+            latitude: "0.0".to_string(),
+            longitude: "0.0".to_string(),
+            name: None,
+        };
+
+        let typed_geo = TypedLexicon::new(geo);
+        let json = serde_json::to_value(&typed_geo).unwrap();
+
+        assert_eq!(json["$type"], "community.lexicon.location.geo");
+        assert_eq!(json["latitude"], "0.0");
+        assert_eq!(json["longitude"], "0.0");
+        assert!(!json.as_object().unwrap().contains_key("name"));
+    }
+}

crates/atproto-record/src/lexicon/mod.rs

···
+//! AT Protocol lexicon type definitions and implementations.
+//!
+//! This module provides Rust implementations of AT Protocol lexicon types,
+//! organized by namespace following the AT Protocol naming conventions.
+//!
+//! # Structure
+//!
+//! The module is organized into two main namespaces:
+//!
+//! - `com.atproto.*` - Core AT Protocol types (e.g., StrongRef)
+//! - `community.lexicon.*` - Community-defined types for social features
+//!
+//! # TypedLexicon Pattern
+//!
+//! Most types in this module follow the TypedLexicon pattern, which automatically
+//! handles the `$type` field required by AT Protocol for type discrimination.
+//! This pattern ensures correct serialization and deserialization of lexicon types.
+//!
+//! # Example
+//!
+//! ```ignore
+//! use atproto_record::lexicon::com::atproto::repo::{StrongRef, TypedStrongRef};
+//!
+//! // Create a strong reference
+//! let strong_ref = StrongRef {
+//!     uri: "at://did:plc:example/collection/record".to_string(),
+//!     cid: "bafyreicid123".to_string(),
+//! };
+//!
+//! // Wrap it with TypedLexicon for automatic $type handling
+//! let typed_ref = TypedStrongRef::new(strong_ref);
+//! ```
+
+mod com_atproto_repo;
+mod community_lexicon_attestation;
+mod community_lexicon_badge;
+mod community_lexicon_calendar_event;
+mod community_lexicon_calendar_rsvp;
+mod community_lexicon_location;
+mod primatives;
+
+pub use primatives::*;
+
+/// AT Protocol core types namespace
+pub mod com {
+    /// AT Protocol namespace
+    pub mod atproto {
+        /// Repository-related types
+        pub mod repo {
+            pub use crate::lexicon::com_atproto_repo::*;
+        }
+    }
+}
+
+/// Community lexicon types namespace
+pub mod community {
+    /// Community lexicon definitions
+    pub mod lexicon {
+        /// Calendar-related types for events and RSVPs
+        pub mod calendar {
+            /// Event-related types
+            pub mod event {
+                pub use crate::lexicon::community_lexicon_calendar_event::*;
+            }
+            /// RSVP-related types
+            pub mod rsvp {
+                pub use crate::lexicon::community_lexicon_calendar_rsvp::*;
+            }
+        }
+        /// Location-related types
+        pub mod location {
+            pub use crate::lexicon::community_lexicon_location::*;
+        }
+
+        /// Attestation and signature types
+        pub mod attestation {
+            pub use crate::lexicon::community_lexicon_attestation::*;
+        }
+    }
+}

crates/atproto-record/src/lexicon/primatives.rs

···
+//! Primitive types used across AT Protocol lexicon definitions.
+//!
+//! This module contains fundamental data types that are referenced by
+//! various AT Protocol lexicon schemas, including blob references,
+//! links, and byte arrays.
+
+use crate::bytes::format as bytes_format;
+use crate::typed::{LexiconType, TypedLexicon};
+use serde::{Deserialize, Serialize};
+
+/// The namespace identifier for blobs
+pub const BLOB_NSID: &str = "blob";
+
+/// Blob reference type for AT Protocol.
+///
+/// Represents a reference to binary data (images, videos, etc.) stored
+/// in the AT Protocol network. The blob itself is not included inline,
+/// but referenced via a CID (Content Identifier).
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::lexicon::{Blob, TypedBlob, Link};
+///
+/// let blob = Blob {
+///     ref_: Link {
+///         link: "bafkreicid123".to_string(),
+///     },
+///     mime_type: "image/jpeg".to_string(),
+///     size: 123456,
+/// };
+///
+/// // Use TypedBlob for automatic $type field handling
+/// let typed_blob = TypedBlob::new(blob);
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Blob {
+    /// Link to the blob content via CID
+    #[serde(rename = "ref")]
+    pub ref_: Link,
+    /// MIME type of the blob content (e.g., "image/jpeg", "video/mp4")
+    #[serde(rename = "mimeType")]
+    pub mime_type: String,
+    /// Size of the blob in bytes
+    pub size: u64,
+}
+
+impl LexiconType for Blob {
+    fn lexicon_type() -> &'static str {
+        BLOB_NSID
+    }
+}
+
+/// Type alias for Blob with automatic $type field handling.
+///
+/// This wrapper ensures that the `$type` field is automatically
+/// added during serialization and validated during deserialization.
+pub type TypedBlob = TypedLexicon<Blob>;
+
+/// Link reference type for AT Protocol.
+///
+/// Represents a content-addressed link using a CID (Content Identifier).
+/// This is used to reference immutable content in the AT Protocol network.
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Link {
+    /// The CID (Content Identifier) as a string
+    #[serde(rename = "$link")]
+    pub link: String,
+}
+
+/// Byte array type for AT Protocol.
+///
+/// Represents raw byte data that is serialized/deserialized as base64.
+/// Used for signatures, hashes, and other binary data that needs to be
+/// transmitted in JSON format.
+///
+/// # Example
+///
+/// ```ignore
+/// let signature = Bytes {
+///     bytes: b"signature data".to_vec(),
+/// };
+/// // Serializes to: {"$bytes": "c2lnbmF0dXJlIGRhdGE="}
+/// ```
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+pub struct Bytes {
+    /// The raw bytes, serialized as base64 in JSON
+    #[serde(rename = "$bytes", with = "bytes_format")]
+    pub bytes: Vec<u8>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_typed_blob_serialization() {
+        // Create a Blob without explicit $type field
+        let blob = Blob {
+            ref_: Link {
+                link: "bafkreitest123".to_string(),
+            },
+            mime_type: "image/png".to_string(),
+            size: 12345,
+        };
+
+        // Wrap it in TypedBlob
+        let typed_blob = TypedLexicon::new(blob);
+
+        // Serialize and verify $type is added
+        let json = serde_json::to_value(&typed_blob).unwrap();
+        assert_eq!(json["$type"], "blob");
+        assert_eq!(json["ref"]["$link"], "bafkreitest123");
+        assert_eq!(json["mimeType"], "image/png");
+        assert_eq!(json["size"], 12345);
+    }
+
+    #[test]
+    fn test_typed_blob_deserialization() {
+        let json = json!({
+            "$type": "blob",
+            "ref": {
+                "$link": "bafkreideserialized"
+            },
+            "mimeType": "video/mp4",
+            "size": 54321
+        });
+
+        let typed_blob: TypedBlob = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed_blob.inner.ref_.link, "bafkreideserialized");
+        assert_eq!(typed_blob.inner.mime_type, "video/mp4");
+        assert_eq!(typed_blob.inner.size, 54321);
+        assert!(typed_blob.has_type_field());
+        assert!(typed_blob.validate().is_ok());
+    }
+
+    #[test]
+    fn test_typed_blob_without_type_field() {
+        // Test that we can deserialize a blob without $type field
+        let json = json!({
+            "ref": {
+                "$link": "bafkreinotype"
+            },
+            "mimeType": "text/plain",
+            "size": 100
+        });
+
+        let typed_blob: TypedBlob = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed_blob.inner.ref_.link, "bafkreinotype");
+        assert_eq!(typed_blob.inner.mime_type, "text/plain");
+        assert_eq!(typed_blob.inner.size, 100);
+        assert!(!typed_blob.has_type_field());
+
+        // Validation should fail because type is required by default
+        assert!(typed_blob.validate().is_err());
+    }
+
+    #[test]
+    fn test_typed_blob_round_trip() {
+        let original = Blob {
+            ref_: Link {
+                link: "bafkreiroundtrip".to_string(),
+            },
+            mime_type: "application/octet-stream".to_string(),
+            size: 999999,
+        };
+
+        let typed = TypedLexicon::new(original.clone());
+
+        let json = serde_json::to_string(&typed).unwrap();
+        let deserialized: TypedBlob = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(deserialized.inner.ref_.link, original.ref_.link);
+        assert_eq!(deserialized.inner.mime_type, original.mime_type);
+        assert_eq!(deserialized.inner.size, original.size);
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_legacy_blob_with_explicit_type() {
+        // Test backward compatibility: deserializing old format with type_ field
+        let json_old_format = r#"{
+            "$type": "blob",
+            "ref": {
+                "$link": "bafkreilegacy"
+            },
+            "mimeType": "image/gif",
+            "size": 777
+        }"#;
+
+        let typed_blob: TypedBlob = serde_json::from_str(json_old_format).unwrap();
+
+        assert_eq!(typed_blob.inner.ref_.link, "bafkreilegacy");
+        assert_eq!(typed_blob.inner.mime_type, "image/gif");
+        assert_eq!(typed_blob.inner.size, 777);
+        assert!(typed_blob.has_type_field());
+
+        // Re-serialize should maintain the $type field
+        let json = serde_json::to_value(&typed_blob).unwrap();
+        assert_eq!(json["$type"], "blob");
+    }
+
+    #[test]
+    fn test_blob_in_context() {
+        // Test using TypedBlob in a larger structure
+        #[derive(Debug, Serialize, Deserialize)]
+        struct TestRecord {
+            title: String,
+            thumbnail: TypedBlob,
+        }
+
+        let record = TestRecord {
+            title: "Test Image".to_string(),
+            thumbnail: TypedLexicon::new(Blob {
+                ref_: Link {
+                    link: "bafkreicontext".to_string(),
+                },
+                mime_type: "image/jpeg".to_string(),
+                size: 256000,
+            }),
+        };
+
+        let json = serde_json::to_value(&record).unwrap();
+
+        assert_eq!(json["title"], "Test Image");
+        assert_eq!(json["thumbnail"]["$type"], "blob");
+        assert_eq!(json["thumbnail"]["ref"]["$link"], "bafkreicontext");
+        assert_eq!(json["thumbnail"]["mimeType"], "image/jpeg");
+        assert_eq!(json["thumbnail"]["size"], 256000);
+    }
+}

crates/atproto-record/src/lib.rs

···
 //! let record = json!({"$type": "app.bsky.feed.post", "text": "Hello!"});
 //! let sig_obj = json!({"issuer": "did:plc:..."});
 //!
-//! let signed = signature::create(&key_data, &record, "did:plc:repo", 
+//! let signed = signature::create(&key_data, &record, "did:plc:repo",
 //!                                "app.bsky.feed.post", sig_obj).await?;
 //!
 //! // Verify a signature
···
 /// across AT Protocol records. Includes support for both required and optional
 /// datetime fields with millisecond precision.
 pub mod datetime;
+
+/// Byte array serialization utilities.
+///
+/// Provides specialized serialization and deserialization for byte arrays
+/// in AT Protocol records, handling base64 encoding with the `$bytes` field format.
+pub mod bytes;
+
+/// AT Protocol lexicon type definitions.
+///
+/// Contains structured type definitions for various AT Protocol lexicons including
+/// badges, calendar events, RSVPs, locations, and attestations. These types follow
+/// the AT Protocol lexicon specifications for data interchange.
+pub mod lexicon;
+
+/// Generic wrapper for handling lexicon types with `$type` fields.
+///
+/// Provides a flexible way to handle the `$type` discriminator field that appears
+/// in many AT Protocol lexicon structures. The wrapper can automatically add type
+/// fields during serialization and validate them during deserialization.
+pub mod typed;

crates/atproto-record/src/signature.rs

···
 //! ```
 
 use atproto_identity::key::{KeyData, sign, validate};
-use serde_json::json;
 use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
+use serde_json::json;
 
 use crate::errors::VerificationError;
 
···
     if let Some(record_map) = sig.as_object_mut() {
         record_map.insert("repository".to_string(), json!(repository));
         record_map.insert("collection".to_string(), json!(collection));
-        record_map.insert("$type".to_string(), json!("community.lexicon.attestation.signature"));
+        record_map.insert(
+            "$type".to_string(),
+            json!("community.lexicon.attestation.signature"),
+        );
     }
 
     // Create a copy of the record with the $sig object for signing.
···
         record_map.remove("$sig");
         record_map.insert("$sig".to_string(), sig);
     }
-
 
     // Create a signature.
     let serialized_signing_record = serde_ipld_dagcbor::to_vec(&signing_record)?;
···
     if let Some(record_map) = proof.as_object_mut() {
         record_map.remove("repository");
         record_map.remove("collection");
-        record_map.insert("signature".to_string(), json!({"$bytes": json!(encoded_signature)}));
-        record_map.insert("$type".to_string(), json!("community.lexicon.attestation.signature"));
+        record_map.insert(
+            "signature".to_string(),
+            json!({"$bytes": json!(encoded_signature)}),
+        );
+        record_map.insert(
+            "$type".to_string(),
+            json!("community.lexicon.attestation.signature"),
+        );
     }
 
     // Add the signature to the original record
···
         let serialized_record = serde_ipld_dagcbor::to_vec(&signed_record)
             .map_err(|error| VerificationError::RecordSerializationFailed { error })?;
 
-        let signature_bytes = URL_SAFE_NO_PAD.decode(&signature_value).map_err(|error| VerificationError::SignatureDecodingFailed { error })?;
+        let signature_bytes = URL_SAFE_NO_PAD
+            .decode(&signature_value)
+            .map_err(|error| VerificationError::SignatureDecodingFailed { error })?;
 
         validate(key_data, &signature_bytes, &serialized_record)
             .map_err(|error| VerificationError::CryptographicValidationFailed { error })?;

crates/atproto-record/src/typed.rs

···
+//! Generic wrapper type for AT Protocol lexicon structures with optional `$type` field handling.
+//!
+//! This module provides a flexible way to handle the `$type` discriminator field that
+//! appears in many AT Protocol lexicon structures. The wrapper can be used when the
+//! type field needs to be validated, automatically added during serialization, or
+//! when it may not always be present.
+
+use serde::de::{DeserializeOwned, MapAccess, Visitor};
+use serde::ser::SerializeMap;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use std::fmt;
+use std::marker::PhantomData;
+
+/// A trait for types that have an associated lexicon type identifier.
+pub trait LexiconType {
+    /// Returns the lexicon type identifier (e.g., "community.lexicon.attestation.signature").
+    fn lexicon_type() -> &'static str;
+
+    /// Returns whether the type field is required for this lexicon type.
+    /// Default is true, but types can override this for optional type fields.
+    fn type_required() -> bool {
+        true
+    }
+}
+
+/// A wrapper type that handles the `$type` field for AT Protocol lexicon structures.
+///
+/// This wrapper provides flexibility in handling the type field:
+/// - Conditionally adds the `$type` field during serialization based on `type_present`
+/// - Validates the `$type` during deserialization if present
+/// - Preserves the presence/absence of `$type` for round-trip compatibility
+/// - Can handle cases where the `$type` field is optional
+///
+/// # Serialization Behavior
+///
+/// - When created with `TypedLexicon::new()`, the `$type` field will be included in serialization
+/// - When created with `TypedLexicon::new_without_type()`, the `$type` field will be omitted
+/// - When deserialized, the presence of `$type` is preserved for round-trip compatibility
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_record::typed::{TypedLexicon, LexiconType};
+/// use serde::{Deserialize, Serialize};
+///
+/// #[derive(Debug, Serialize, Deserialize)]
+/// struct MyRecord {
+///     name: String,
+///     value: i32,
+/// }
+///
+/// impl LexiconType for MyRecord {
+///     fn lexicon_type() -> &'static str {
+///         "com.example.myrecord"
+///     }
+/// }
+///
+/// // With type field
+/// let record = MyRecord { name: "test".to_string(), value: 42 };
+/// let typed = TypedLexicon::new(record);
+/// let json = serde_json::to_string(&typed).unwrap();
+/// assert!(json.contains("\"$type\":\"com.example.myrecord\""));
+///
+/// // Without type field
+/// let record2 = MyRecord { name: "test2".to_string(), value: 43 };
+/// let typed2 = TypedLexicon::new_without_type(record2);
+/// let json2 = serde_json::to_string(&typed2).unwrap();
+/// assert!(!json2.contains("\"$type\""));
+/// ```
+#[derive(Debug, Clone, PartialEq)]
+pub struct TypedLexicon<T: LexiconType + PartialEq> {
+    /// The inner value being wrapped
+    pub inner: T,
+    /// Whether the type field was explicitly present during deserialization
+    type_present: bool,
+}
+
+impl<T: LexiconType + PartialEq> TypedLexicon<T> {
+    /// Creates a new TypedLexicon wrapper that will include the `$type` field when serialized.
+    pub fn new(inner: T) -> Self {
+        Self {
+            inner,
+            type_present: true,
+        }
+    }
+
+    /// Creates a new TypedLexicon wrapper that will NOT include the `$type` field when serialized.
+    pub fn new_without_type(inner: T) -> Self {
+        Self {
+            inner,
+            type_present: false,
+        }
+    }
+
+    /// Returns whether the type field was present during deserialization.
+    pub fn has_type_field(&self) -> bool {
+        self.type_present
+    }
+
+    /// Validates that the type field is present if required.
+    pub fn validate(&self) -> Result<(), String> {
+        if T::type_required() && !self.type_present {
+            return Err(format!(
+                "Missing required $type field for {}",
+                T::lexicon_type()
+            ));
+        }
+        Ok(())
+    }
+
+    /// Consumes the wrapper and returns the inner value.
+    pub fn into_inner(self) -> T {
+        self.inner
+    }
+}
+
+impl<T> Serialize for TypedLexicon<T>
+where
+    T: LexiconType + Serialize + PartialEq,
+{
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        // Get the serialized form of the inner value
+        let value = serde_json::to_value(&self.inner).map_err(serde::ser::Error::custom)?;
+
+        if let serde_json::Value::Object(mut map) = value {
+            // Only add the $type field if type_present is true
+            if self.type_present {
+                map.insert(
+                    "$type".to_string(),
+                    serde_json::Value::String(T::lexicon_type().to_string()),
+                );
+            }
+
+            // Serialize the modified map
+            let mut ser_map = serializer.serialize_map(Some(map.len()))?;
+            for (k, v) in map {
+                ser_map.serialize_entry(&k, &v)?;
+            }
+            ser_map.end()
+        } else {
+            // If it's not an object, just serialize as-is (shouldn't happen with proper structs)
+            self.inner.serialize(serializer)
+        }
+    }
+}
+
+impl<'de, T> Deserialize<'de> for TypedLexicon<T>
+where
+    T: LexiconType + DeserializeOwned + PartialEq,
+{
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        struct TypedLexiconVisitor<T: LexiconType + PartialEq>(PhantomData<T>);
+
+        impl<'de, T> Visitor<'de> for TypedLexiconVisitor<T>
+        where
+            T: LexiconType + DeserializeOwned + PartialEq,
+        {
+            type Value = TypedLexicon<T>;
+
+            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+                formatter.write_str("a lexicon object")
+            }
+
+            fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+            where
+                A: MapAccess<'de>,
+            {
+                let mut obj = serde_json::Map::new();
+                let mut type_found = false;
+                let expected_type = T::lexicon_type();
+
+                while let Some((key, value)) = map.next_entry::<String, serde_json::Value>()? {
+                    if key == "$type" {
+                        type_found = true;
+                        // Validate the type matches
+                        if let serde_json::Value::String(ref type_str) = value {
+                            if type_str != expected_type {
+                                return Err(serde::de::Error::custom(format!(
+                                    "Invalid $type field: expected '{}', found '{}'",
+                                    expected_type, type_str
+                                )));
+                            }
+                        } else {
+                            return Err(serde::de::Error::custom("$type field must be a string"));
+                        }
+                        // Don't include $type in the object we deserialize to T
+                    } else {
+                        obj.insert(key, value);
+                    }
+                }
+
+                // Deserialize the inner value from the cleaned object
+                let inner = serde_json::from_value(serde_json::Value::Object(obj))
+                    .map_err(serde::de::Error::custom)?;
+
+                Ok(TypedLexicon {
+                    inner,
+                    type_present: type_found,
+                })
+            }
+        }
+
+        deserializer.deserialize_map(TypedLexiconVisitor(PhantomData))
+    }
+}
+
+// Allow dereferencing to the inner type
+impl<T: LexiconType + PartialEq> std::ops::Deref for TypedLexicon<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<T: LexiconType + PartialEq> std::ops::DerefMut for TypedLexicon<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+    struct TestRecord {
+        name: String,
+        value: i32,
+    }
+
+    impl LexiconType for TestRecord {
+        fn lexicon_type() -> &'static str {
+            "test.lexicon.record"
+        }
+    }
+
+    #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
+    struct OptionalTypeRecord {
+        data: String,
+    }
+
+    impl LexiconType for OptionalTypeRecord {
+        fn lexicon_type() -> &'static str {
+            "test.lexicon.optional"
+        }
+
+        fn type_required() -> bool {
+            false
+        }
+    }
+
+    #[test]
+    fn test_serialization_adds_type() {
+        let record = TestRecord {
+            name: "test".to_string(),
+            value: 42,
+        };
+        let typed = TypedLexicon::new(record);
+
+        let json = serde_json::to_value(&typed).unwrap();
+
+        assert_eq!(json["$type"], "test.lexicon.record");
+        assert_eq!(json["name"], "test");
+        assert_eq!(json["value"], 42);
+    }
+
+    #[test]
+    fn test_deserialization_validates_type() {
+        let json = json!({
+            "$type": "test.lexicon.record",
+            "name": "test",
+            "value": 42
+        });
+
+        let typed: TypedLexicon<TestRecord> = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed.inner.name, "test");
+        assert_eq!(typed.inner.value, 42);
+        assert!(typed.has_type_field());
+    }
+
+    #[test]
+    fn test_deserialization_without_type() {
+        let json = json!({
+            "name": "test",
+            "value": 42
+        });
+
+        let typed: TypedLexicon<TestRecord> = serde_json::from_value(json).unwrap();
+
+        assert_eq!(typed.inner.name, "test");
+        assert_eq!(typed.inner.value, 42);
+        assert!(!typed.has_type_field());
+    }
+
+    #[test]
+    fn test_deserialization_wrong_type() {
+        let json = json!({
+            "$type": "wrong.type",
+            "name": "test",
+            "value": 42
+        });
+
+        let result: Result<TypedLexicon<TestRecord>, _> = serde_json::from_value(json);
+        assert!(result.is_err());
+
+        let err = result.unwrap_err().to_string();
+        assert!(err.contains("expected 'test.lexicon.record'"));
+        assert!(err.contains("found 'wrong.type'"));
+    }
+
+    #[test]
+    fn test_validation_required_type() {
+        let typed = TypedLexicon::new_without_type(TestRecord {
+            name: "test".to_string(),
+            value: 42,
+        });
+
+        let result = typed.validate();
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Missing required $type field"));
+    }
+
+    #[test]
+    fn test_validation_optional_type() {
+        let typed = TypedLexicon::new_without_type(OptionalTypeRecord {
+            data: "test".to_string(),
+        });
+
+        let result = typed.validate();
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_round_trip() {
+        let original = TestRecord {
+            name: "round trip".to_string(),
+            value: 123,
+        };
+        let typed = TypedLexicon::new(original.clone());
+
+        let json = serde_json::to_string(&typed).unwrap();
+        let deserialized: TypedLexicon<TestRecord> = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(deserialized.inner, original);
+        assert!(deserialized.has_type_field());
+    }
+
+    #[test]
+    fn test_deref() {
+        let typed = TypedLexicon::new(TestRecord {
+            name: "deref test".to_string(),
+            value: 456,
+        });
+
+        // Can access fields through deref
+        assert_eq!(typed.name, "deref test");
+        assert_eq!(typed.value, 456);
+    }
+
+    #[test]
+    fn test_new_without_type_omits_type_field() {
+        let record = TestRecord {
+            name: "no type".to_string(),
+            value: 99,
+        };
+        let typed = TypedLexicon::new_without_type(record);
+
+        let json = serde_json::to_value(&typed).unwrap();
+
+        // Should NOT have $type field
+        assert!(!json.as_object().unwrap().contains_key("$type"));
+        assert_eq!(json["name"], "no type");
+        assert_eq!(json["value"], 99);
+    }
+
+    #[test]
+    fn test_round_trip_preserves_type_absence() {
+        // Deserialize without $type
+        let json_without_type = json!({
+            "name": "test",
+            "value": 42
+        });
+
+        let typed: TypedLexicon<TestRecord> = serde_json::from_value(json_without_type).unwrap();
+        assert!(!typed.has_type_field());
+
+        // Re-serialize should NOT add $type
+        let reserialized = serde_json::to_value(&typed).unwrap();
+        assert!(!reserialized.as_object().unwrap().contains_key("$type"));
+        assert_eq!(reserialized["name"], "test");
+        assert_eq!(reserialized["value"], 42);
+    }
+
+    #[test]
+    fn test_round_trip_preserves_type_presence() {
+        // Deserialize with $type
+        let json_with_type = json!({
+            "$type": "test.lexicon.record",
+            "name": "test",
+            "value": 42
+        });
+
+        let typed: TypedLexicon<TestRecord> = serde_json::from_value(json_with_type).unwrap();
+        assert!(typed.has_type_field());
+
+        // Re-serialize should preserve $type
+        let reserialized = serde_json::to_value(&typed).unwrap();
+        assert_eq!(reserialized["$type"], "test.lexicon.record");
+        assert_eq!(reserialized["name"], "test");
+        assert_eq!(reserialized["value"], 42);
+    }
+
+    #[test]
+    fn test_optional_type_record_behavior() {
+        // Test with type_required() = false
+
+        // new() should still add $type
+        let with_type = TypedLexicon::new(OptionalTypeRecord {
+            data: "with".to_string(),
+        });
+        let json = serde_json::to_value(&with_type).unwrap();
+        assert_eq!(json["$type"], "test.lexicon.optional");
+
+        // new_without_type() should omit $type
+        let without_type = TypedLexicon::new_without_type(OptionalTypeRecord {
+            data: "without".to_string(),
+        });
+        let json2 = serde_json::to_value(&without_type).unwrap();
+        assert!(!json2.as_object().unwrap().contains_key("$type"));
+
+        // Both should validate successfully since type is optional
+        assert!(with_type.validate().is_ok());
+        assert!(without_type.validate().is_ok());
+    }
+}