serialization_format Enum

namespace keychain → enum class serialization_format

Overview

The serialization_format enumeration specifies different data serialization formats supported by Keychain Core for data exchange, storage, and interoperability.

Syntax

namespace keychain {
    enum class serialization_format {
        XML,        // Extensible Markup Language
        JSON,       // JavaScript Object Notation
        PROTOBUF,   // Protocol Buffers (binary)
        BINARY      // Native binary format
    };
}

Members

XML

Value: serialization_format::XML

Extensible Markup Language - structured markup format.

Characteristics: * Human-readable text format * Self-describing with schema validation * Extensive tooling support * Larger payload size * Good for document-oriented data

Advantages: * Wide industry support * Schema validation capabilities * Namespace support * Human-readable for debugging

Disadvantages: * Verbose syntax * Larger message sizes * Slower parsing performance

JSON

Value: serialization_format::JSON

JavaScript Object Notation - lightweight data-interchange format.

Characteristics: * Human-readable text format * Simple syntax and structure * Native JavaScript support * Moderate payload size * Excellent web compatibility

Advantages: * Lightweight and fast parsing * Ubiquitous support across languages * Human-readable * Web API standard

Disadvantages: * Limited data types * No schema validation (without additional tools) * No comments support

PROTOBUF

Value: serialization_format::PROTOBUF

Protocol Buffers - Google’s language-neutral serialization mechanism.

Characteristics: * Binary format (not human-readable) * Compact and efficient * Strong typing with schema * Cross-language compatibility * Excellent performance

Advantages: * Very compact binary format * Fast serialization/deserialization * Strong typing and versioning * Code generation for multiple languages

Disadvantages: * Not human-readable * Requires schema definition * Binary compatibility concerns

BINARY

Value: serialization_format::BINARY

Native binary format optimized for Keychain Core.

Characteristics: * Proprietary binary format * Maximum efficiency * Optimized for Keychain data types * Smallest payload size * Fastest processing

Advantages: * Optimal performance for Keychain operations * Minimal overhead * Type-specific optimizations * Version-aware format

Disadvantages: * Not human-readable * Keychain-specific format * Limited interoperability

Usage

#include <keychain/keychain.h>

// Serialize data in different formats
keychain::serialized_data data;
data.set_value("Hello, World!");

// Convert to different formats
std::string xml_output = data.serialize(keychain::serialization_format::XML);
std::string json_output = data.serialize(keychain::serialization_format::JSON);
std::vector<uint8_t> protobuf_output = data.serialize_binary(keychain::serialization_format::PROTOBUF);
std::vector<uint8_t> binary_output = data.serialize_binary(keychain::serialization_format::BINARY);

// Deserialize from different formats
keychain::serialized_data from_xml;
from_xml.deserialize(xml_output, keychain::serialization_format::XML);

keychain::serialized_data from_json;
from_json.deserialize(json_output, keychain::serialization_format::JSON);

// Check format compatibility
bool supports_format(keychain::serialization_format format) {
    switch (format) {
        case keychain::serialization_format::XML:
        case keychain::serialization_format::JSON:
        case keychain::serialization_format::PROTOBUF:
        case keychain::serialization_format::BINARY:
            return true;
        default:
            return false;
    }
}

Format Comparison

Format Human Readable Size Speed Interoperability Schema Support

XML

✓

Large

Slow

Excellent

✓ (XSD)

JSON

✓

Medium

Fast

Excellent

Limited (JSON Schema)

PROTOBUF

✗

Small

Very Fast

Good

✓ (Native)

BINARY

✗

Smallest

Fastest

Limited

✓ (Native)

Example Outputs

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<serializedData>
    <type>STRING</type>
    <value>Hello, World!</value>
    <metadata>
        <created>2024-01-15T10:30:00Z</created>
        <version>3.0</version>
    </metadata>
</serializedData>

JSON Format

{
  "type": "STRING",
  "value": "Hello, World!",
  "metadata": {
    "created": "2024-01-15T10:30:00Z",
    "version": "3.0"
  }
}

Protocol Buffers Schema

syntax = "proto3";

message SerializedData {
  DataType type = 1;
  string value = 2;
  map<string, string> metadata = 3;
}

enum DataType {
  UNKNOWN = 0;
  STRING = 1;
  INT = 2;
  // ... other types
}

Performance Characteristics

// Performance benchmark example
void benchmark_serialization_formats() {
    keychain::serialized_data large_data;
    // Fill with 10MB of test data

    auto benchmark_format = [&](keychain::serialization_format format) {
        auto start = std::chrono::high_resolution_clock::now();

        // Serialize
        auto serialized = large_data.serialize(format);

        // Deserialize
        keychain::serialized_data deserialized;
        deserialized.deserialize(serialized, format);

        auto end = std::chrono::high_resolution_clock::now();
        auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);

        std::cout << "Format " << to_string(format)
                 << ": " << duration.count() << "ms, "
                 << "Size: " << serialized.size() << " bytes" << std::endl;
    };

    benchmark_format(keychain::serialization_format::XML);
    benchmark_format(keychain::serialization_format::JSON);
    benchmark_format(keychain::serialization_format::PROTOBUF);
    benchmark_format(keychain::serialization_format::BINARY);
}

Use Case Recommendations

XML Format

Best for: * Enterprise integration * Document-oriented data * Strong schema validation requirements * Legacy system compatibility

Example:

// Configuration files, enterprise APIs
keychain::serialization_format config_format = keychain::serialization_format::XML;

JSON Format

Best for: * Web APIs and services * Human-readable configuration * JavaScript applications * RESTful interfaces

Example:

// Web API responses, configuration files
keychain::serialization_format api_format = keychain::serialization_format::JSON;

Protocol Buffers

Best for: * High-performance RPC systems * Microservices communication * Language-neutral APIs * Version-aware protocols

Example:

// Internal service communication
keychain::serialization_format rpc_format = keychain::serialization_format::PROTOBUF;

Binary Format

Best for: * Maximum performance requirements * Internal Keychain operations * Minimal bandwidth scenarios * Real-time applications

Example:

// High-frequency operations, embedded systems
keychain::serialization_format perf_format = keychain::serialization_format::BINARY;

Migration and Versioning

// Handle format migration
keychain::serialized_data migrate_format(
    const keychain::serialized_data& data,
    keychain::serialization_format from_format,
    keychain::serialization_format to_format) {

    // Serialize in old format
    auto serialized = data.serialize(from_format);

    // Deserialize and re-serialize in new format
    keychain::serialized_data migrated;
    migrated.deserialize(serialized, from_format);

    return migrated;
}

// Version-aware deserialization
keychain::serialized_data deserialize_with_fallback(
    const std::string& data_str,
    const std::vector<keychain::serialization_format>& formats) {

    for (auto format : formats) {
        try {
            keychain::serialized_data result;
            result.deserialize(data_str, format);
            return result;
        } catch (const std::exception&) {
            continue; // Try next format
        }
    }

    throw std::runtime_error("Unable to deserialize with any supported format");
}

See Also

  • gateway - Data serialization operations

  • {json-spec}[JSON Specification (RFC 7159)]

  • {xml-spec}[XML 1.0 Specification]

  • {protobuf-guide}[Protocol Buffers Developer Guide]