Keychain Core Documentation
Version:

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

YES

Large

Slow

Excellent

YES (XSD)

JSON

YES

Medium

Fast

Excellent

Limited (JSON Schema)

PROTOBUF

NO

Small

Very Fast

Good

YES (Native)

BINARY

NO

Smallest

Fastest

Limited

YES (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]