Crystal CBOR (RFC 8949)

A lightweight, dependency-free, high-performance and RFC 8949 compliant CBOR (Concise Binary Object Representation) implementation for the Crystal programming language.

Key Features

• [x] Full RFC 8949 Compliance: Supports all Major Types (0 to 7).
• [x] Streaming Support: Encode and decode directly to/from any IO (files, sockets, memory) without loading entire payloads into RAM.
• [x] Semantic Tags: Native support for CBOR Tags (Major Type 6) to add metadata to your data structures.
• [x] Type Safety: Seamless integration with Crystal’s type system using the CBOR::Value alias.

Roadmap & Future Enhancements

• [ ] CBOR::Serializable Module: Implement a high-level API similar to JSON::Serializable for seamless object mapping using class annotations.
• [ ] Extensible Tag Registry: Develop a plugin system to register custom converters for specific CBOR Tags, enabling automatic conversion between custom types and binary data.
• [ ] Diagnostic & Debugging Tools: Add utilities for human-readable CBOR diagnostic notation and hex/Base64 stream inspection to simplify debugging.

Installation

Add the library to your shard.yml:

dependencies:
  crystal_cbor:
    github: mamiysr/crystal_cbor

Then, install the dependencies:

shards install

Usage

Basic Encoding and Decoding

Transforming data structures to binary and back is straightforward.

require "crystal_cbor"

# Create a data structure
data = {
  "name"    => "Crystal",
  "version" => 1.18,
  "active"  => true,
  "tags"    => [1, 2, 3]
}

# Encode: Hash -> Bytes
encoded = CBOR.encode(data)
puts "Encoded size: #{encoded.size} bytes"

# Decode: Bytes -> CBOR::Value -> Hash
decoded = CBOR.decode(encoded).as(Hash)
puts decoded["name"] # => "Crystal"

Streaming (IO-Based Processing)

For large datasets, you can process data chunk-by-chunk using Crystal's IO system to keep memory usage low.

# Write to a file (Encoding)
File.open("data.cbor", "w") do |file|
  CBOR.encode({"sensor_id" => 12345}, file)
end

# Read from a file (Decoding)
File.open("data.cbor", "r") do |file|
  decoded = CBOR.decode(file)
  puts decoded
end

Working with CBOR Tags

Tags are used to provide extra semantic meaning to data (e.g., indicating a string is actually a Date or a UUID).

# Manually create a Tag (e.g., Tag 1 for Date/Time)
date_tag = CBOR::Tag.new(1_u64, "2026-01-14")

encoded = CBOR.encode(date_tag)
decoded = CBOR.decode(encoded).as(CBOR::Tag)

puts "Tag ID: #{decoded.id}"      # => 1
puts "Content: #{decoded.content}" # => "2026-01-14"

Contributing

1. Fork it (https://github.com/mamiysr/cbor.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT License.