CBOR Tags Reference

CBOR tags (Major Type 6) provide semantic information about data values. Tags are integers that prefix a data item to give it additional meaning according to a registry maintained by IANA.

Table of Contents

• Overview
• Built-in Tags
• Using Tags
• Creating Custom Tags
• IANA Registry

Overview

Tags in CBOR follow this structure:

Tag(tag_number, data_item)

Where:

• tag_number is an integer identifying the semantic meaning
• data_item is any CBOR object that the tag applies to

This library provides implementations for commonly used tags and a generic tag handler for unsupported tags.

Built-in Tags

Date/Time Tags

Tag 0: Date/Time String (RFC 3339)

Encodes a date/time string in RFC 3339 format.

Class: CBOR\Tag\DatetimeTag Spec: RFC 8949 § 3.4.1

use CBOR\Tag\DatetimeTag;
use CBOR\TextStringObject;

// Create from RFC 3339 string
$tag = DatetimeTag::create(
    TextStringObject::create('2024-01-15T10:30:00Z')
);

// Normalize to PHP DateTimeImmutable
$dateTime = $tag->normalize();
echo $dateTime->format('Y-m-d H:i:s'); // 2024-01-15 10:30:00

Accepts: TextStringObject or IndefiniteLengthTextStringObject Returns: DateTimeImmutable when normalized

Tag 1: Epoch-Based Date/Time

Encodes a POSIX timestamp (seconds since Unix epoch: 1970-01-01 00:00:00 UTC).

Class: CBOR\Tag\TimestampTag Spec: RFC 8949 § 3.4.2

use CBOR\Tag\TimestampTag;
use CBOR\UnsignedIntegerObject;

// Create from Unix timestamp
$tag = TimestampTag::create(
    UnsignedIntegerObject::create(time())
);

// Normalize to PHP DateTimeImmutable
$dateTime = $tag->normalize();
echo $dateTime->format('c'); // ISO 8601 format

Accepts: UnsignedIntegerObject, NegativeIntegerObject, or float objects Returns: DateTimeImmutable when normalized

Big Number Tags

Tag 2: Unsigned Bignum

Encodes an arbitrarily large positive integer as a byte string.

Class: CBOR\Tag\UnsignedBigIntegerTag Spec: RFC 8949 § 3.4.3

use CBOR\Tag\UnsignedBigIntegerTag;
use CBOR\ByteStringObject;

// The byte string contains the big-endian representation
$tag = UnsignedBigIntegerTag::create(
    ByteStringObject::create(hex2bin('0123456789ABCDEF'))
);

// Normalize to string representation
$value = $tag->normalize(); // "81985529216486895"

Accepts: ByteStringObject or IndefiniteLengthByteStringObject Returns: Numeric string when normalized

Tag 3: Negative Bignum

Encodes an arbitrarily large negative integer. The value is -1 minus the unsigned integer encoded in the byte string.

Class: CBOR\Tag\NegativeBigIntegerTag Spec: RFC 8949 § 3.4.3

use CBOR\Tag\NegativeBigIntegerTag;
use CBOR\ByteStringObject;

// Represents: -1 - unsigned_value
$tag = NegativeBigIntegerTag::create(
    ByteStringObject::create(hex2bin('FF'))
);

$value = $tag->normalize(); // "-256"

Accepts: ByteStringObject or IndefiniteLengthByteStringObject Returns: Numeric string when normalized

Fractional Number Tags

Tag 4: Decimal Fraction

Encodes a decimal fraction as: mantissa × 10^exponent

Class: CBOR\Tag\DecimalFractionTag Spec: RFC 8949 § 3.4.4 Requires: ext-bcmath

use CBOR\Tag\DecimalFractionTag;
use CBOR\NegativeIntegerObject;
use CBOR\UnsignedIntegerObject;

// Method 1: From exponent and mantissa
// Represents: 1234 × 10^(-2) = 12.34
$tag = DecimalFractionTag::createFromExponentAndMantissa(
    NegativeIntegerObject::create(-2),  // exponent
    UnsignedIntegerObject::create(1234) // mantissa
);

echo $tag->normalize(); // "12.34"

// Method 2: From PHP float
$tag = DecimalFractionTag::createFromFloat(3.14159, precision: 5);
echo $tag->normalize(); // "3.14159"

// Method 3: From list
use CBOR\ListObject;

$tag = DecimalFractionTag::create(
    ListObject::create([
        NegativeIntegerObject::create(-2),
        UnsignedIntegerObject::create(1234)
    ])
);

Accepts: ListObject with exactly 2 elements [exponent, mantissa] Returns: String representation of the decimal value when normalized

Tag 5: Bigfloat

Encodes a binary floating-point value as: mantissa × 2^exponent

Class: CBOR\Tag\BigFloatTag Spec: RFC 8949 § 3.4.4 Requires: ext-bcmath

use CBOR\Tag\BigFloatTag;
use CBOR\NegativeIntegerObject;
use CBOR\UnsignedIntegerObject;

// Represents: 5 × 2^(-2) = 1.25
$tag = BigFloatTag::createFromExponentAndMantissa(
    NegativeIntegerObject::create(-2),  // exponent (base 2)
    UnsignedIntegerObject::create(5)    // mantissa
);

echo $tag->normalize(); // "1.25"

// From PHP float
$tag = BigFloatTag::createFromFloat(3.14159);

Accepts: ListObject with exactly 2 elements [exponent, mantissa] Returns: String representation of the value when normalized

Encoded Data Tags

Tag 21: Base64url Encoding (Expected Conversion)

Indicates that the byte string should be encoded as base64url when converted to text.

Class: CBOR\Tag\Base64UrlEncodingTag Spec: RFC 8949 § 3.4.5.2

use CBOR\Tag\Base64UrlEncodingTag;
use CBOR\ByteStringObject;

$tag = Base64UrlEncodingTag::create(
    ByteStringObject::create('Hello World!')
);

// The tag hints that this should be base64url encoded
$encoded = $tag->normalize(); // "SGVsbG8gV29ybGQh"

Accepts: ByteStringObject or IndefiniteLengthByteStringObject Returns: Base64url-encoded string when normalized

Tag 22: Base64 Encoding (Expected Conversion)

Indicates that the byte string should be encoded as base64 when converted to text.

Class: CBOR\Tag\Base64EncodingTag Spec: RFC 8949 § 3.4.5.2

use CBOR\Tag\Base64EncodingTag;
use CBOR\ByteStringObject;

$tag = Base64EncodingTag::create(
    ByteStringObject::create('Hello World!')
);

$encoded = $tag->normalize(); // "SGVsbG8gV29ybGQh"

Accepts: ByteStringObject or IndefiniteLengthByteStringObject Returns: Base64-encoded string when normalized

Tag 23: Base16 Encoding (Expected Conversion)

Indicates that the byte string should be encoded as hexadecimal when converted to text.

Class: CBOR\Tag\Base16EncodingTag Spec: RFC 8949 § 3.4.5.2

use CBOR\Tag\Base16EncodingTag;
use CBOR\ByteStringObject;

$tag = Base16EncodingTag::create(
    ByteStringObject::create('Hello')
);

$encoded = $tag->normalize(); // "48656c6c6f"

Accepts: ByteStringObject or IndefiniteLengthByteStringObject Returns: Hexadecimal string when normalized

Semantic Tags

Tag 32: URI

Indicates that the text string contains a URI as defined by RFC 3986.

Class: CBOR\Tag\UriTag Spec: RFC 8949 § 3.4.5.3

use CBOR\Tag\UriTag;
use CBOR\TextStringObject;

$tag = UriTag::create(
    TextStringObject::create('https://example.com/path?query=value')
);

$uri = $tag->normalize(); // "https://example.com/path?query=value"

Accepts: TextStringObject or IndefiniteLengthTextStringObject Returns: URI string when normalized

Tag 33: Base64url Encoded Text

The text string contains data that is already base64url encoded.

Class: CBOR\Tag\Base64UrlTag Spec: RFC 8949 § 3.4.5.2

use CBOR\Tag\Base64UrlTag;
use CBOR\TextStringObject;

$tag = Base64UrlTag::create(
    TextStringObject::create('SGVsbG8gV29ybGQh')
);

Accepts: TextStringObject or IndefiniteLengthTextStringObject

Tag 34: Base64 Encoded Text

The text string contains data that is already base64 encoded.

Class: CBOR\Tag\Base64Tag Spec: RFC 8949 § 3.4.5.2

use CBOR\Tag\Base64Tag;
use CBOR\TextStringObject;

$tag = Base64Tag::create(
    TextStringObject::create('SGVsbG8gV29ybGQh')
);

Accepts: TextStringObject or IndefiniteLengthTextStringObject

Tag 36: MIME Message

Indicates that the byte string or text string contains a MIME message (including email).

Class: CBOR\Tag\MimeTag Spec: RFC 8949 § 3.4.5.3

use CBOR\Tag\MimeTag;
use CBOR\TextStringObject;

$mimeMessage = "Content-Type: text/plain\r\n\r\nHello World!";

$tag = MimeTag::create(
    TextStringObject::create($mimeMessage)
);

Accepts: TextStringObject, IndefiniteLengthTextStringObject, ByteStringObject, or IndefiniteLengthByteStringObject

Special CBOR Tags

Tag 24: Encoded CBOR Data Item

Indicates that the byte string contains a CBOR-encoded data item.

Class: CBOR\Tag\CBOREncodingTag Spec: RFC 8949 § 3.4.5.1

use CBOR\Tag\CBOREncodingTag;
use CBOR\ByteStringObject;
use CBOR\UnsignedIntegerObject;

// Encode a CBOR object
$innerObject = UnsignedIntegerObject::create(42);
$encoded = (string) $innerObject;

// Wrap it in Tag 24
$tag = CBOREncodingTag::create(
    ByteStringObject::create($encoded)
);

// Can be decoded later
$decoder = Decoder::create();
$decoded = $decoder->decode(StringStream::create($tag->getValue()->getValue()));

Accepts: ByteStringObject

Tag 55799: Self-Described CBOR

A "magic number" that marks the beginning of a CBOR data stream. This helps decoders quickly identify CBOR-encoded data.

Class: CBOR\Tag\SelfDescribeCBORTag Spec: RFC 8949 § 3.4.6 Tag Number: 55799 (0xd9d9f7 in hex)

use CBOR\Tag\SelfDescribeCBORTag;
use CBOR\MapObject;
use CBOR\TextStringObject;

// Wrap any CBOR object with self-describe tag
$data = MapObject::create()
    ->add(TextStringObject::create('key'), TextStringObject::create('value'));

$selfDescribed = SelfDescribeCBORTag::create($data);

// When encoded, this will start with the bytes: d9 d9 f7
$encoded = (string) $selfDescribed;

// Retrieve the wrapped object
$innerObject = $selfDescribed->getCBORObject();

Accepts: Any CBORObject Purpose: Allows decoders to rapidly identify CBOR data without parsing

Using Tags

Encoding with Tags

use CBOR\Tag\TimestampTag;
use CBOR\UnsignedIntegerObject;

// Create the data
$timestamp = UnsignedIntegerObject::create(time());

// Wrap with a tag
$tagged = TimestampTag::create($timestamp);

// Encode to CBOR binary
$encoded = (string) $tagged;

Decoding Tagged Data

use CBOR\Decoder;
use CBOR\StringStream;

$decoder = Decoder::create();
$decoded = $decoder->decode(StringStream::create($encoded));

// The decoder automatically recognizes registered tags
if ($decoded instanceof TimestampTag) {
    $dateTime = $decoded->normalize();
    echo $dateTime->format('Y-m-d H:i:s');
}

Accessing Tagged Values

// Get the wrapped object
$wrappedObject = $tagged->getValue();

// Get additional data (if any)
$data = $tagged->getData();

// Get the tag number
$tagId = $tagged::getTagId();

Creating Custom Tags

See Creating Custom Tags for a comprehensive guide on implementing your own tag types.

IANA Registry

The CBOR Tags registry is maintained by IANA. This library implements the most commonly used tags from the registry.

Full Registry: IANA CBOR Tags

Tag Summary Table

Unsupported Tags

For tags not implemented by this library, use GenericTag:

use CBOR\Tag\GenericTag;
use CBOR\TextStringObject;

// Create a tag with any tag number
$tag = GenericTag::createFromLoadedData(
    $additionalInformation,
    $data,
    TextStringObject::create('custom data')
);

Best Practices

1. Choose the Right Tag: Use standard IANA-registered tags when available for interoperability
2. Validate Data Types: Ensure the wrapped object matches the expected type for the tag
3. Handle Unknown Tags: Be prepared to handle GenericTag for unrecognized tag numbers
4. Check Extensions: Some tags require specific PHP extensions (e.g., bcmath for decimal fractions)
5. Normalize Appropriately: Use normalize() to convert tagged values to native PHP types

← Back to Documentation Index | Creating Custom Tags →