EntropyCanvas::Schema::ComponentSchema

EntropyCanvas::Schema::ComponentSchema

Component schema definition. More…

#include <ComponentSchema.h>

Public Functions

	Name
std::string	toCanonicalString() const Build canonical string representation for hashing.
bool	isStructurallyCompatible(const ComponentSchema & other) const Check structural compatibility with another schema.
Result< ComponentSchema >	create(const std::string & appId, const std::string & componentName, uint32_t schemaVersion, const std::vector< PropertyDefinition > & properties, size_t totalSize, bool isPublic =false) Create and validate a component schema.
ComponentTypeHash	computeTypeHash(const std::string & appId, const std::string & componentName, uint32_t schemaVersion, const PropertyHash & structuralHash) Compute component type hash.
PropertyHash	computeStructuralHash(const std::vector< PropertyDefinition > & properties) Compute structural hash from properties.
Result< void >	canReadFrom(const ComponentSchema & other) const Check if this schema can read from another schema.

Public Attributes

	Name
ComponentTypeHash	typeHash Unique component type identifier.
size_t	totalSize Total component size in bytes.
PropertyHash	structuralHash Hash of field layout.
uint32_t	schemaVersion Schema version for evolution.
std::vector< PropertyDefinition >	properties
bool	isPublic Whether schema is published for discovery.
std::string	componentName Human-readable component name.
std::string	appId Originating application ID.

Detailed Description

struct EntropyCanvas::Schema::ComponentSchema;

Component schema definition.

Describes the complete structure of a component type including all properties. Used for validation and cross-application compatibility checking.

Schema Evolution:

• Application decides compatibility policy
• Structural hash provides fast equality check
• canReadFrom() provides subset compatibility checking
• Applications control how to handle version differences

Privacy:

• Schemas are private by default
• Applications opt-in to publishing via isPublic flag
• Only public schemas are discoverable by other applications

Public Functions Documentation

function toCanonicalString

std::string toCanonicalString() const

Build canonical string representation for hashing.

Return: Canonical string representation

Format: “{appId}.{componentName}@{version}{prop1:type1:offset1:size1,…}”

• Properties sorted by name (ASCII lexicographic order)
• All identifiers must be ASCII [a-zA-Z0-9_]
• Used as input for hash computation

Example: “MyApp.Transform@1{position:Vec3:0:12,rotation:Quat:12:16}“

function isStructurallyCompatible

inline bool isStructurallyCompatible(
    const ComponentSchema & other
) const

Check structural compatibility with another schema.

Parameters:

• other Schema to compare against

Return: true if structurally compatible

Two schemas are structurally compatible if they have identical field layouts (same fields, types, and offsets).

This is a fast O(1) check using structural hash comparison.

function create

static Result< ComponentSchema > create(
    const std::string & appId,
    const std::string & componentName,
    uint32_t schemaVersion,
    const std::vector< PropertyDefinition > & properties,
    size_t totalSize,
    bool isPublic =false
)

Create and validate a component schema.

Parameters:

• appId Application identifier
• componentName Component type name
• schemaVersion Version number
• properties List of property definitions
• totalSize Total struct size in bytes
• isPublic Whether to publish for discovery (default: false)

Return: Result with ComponentSchema on success, error on validation failure

Validates field definitions and computes hashes automatically. Checks for:

• Empty app ID or component name
• Empty properties list
• Invalid property types
• Overlapping field offsets
• Fields extending beyond totalSize

std::vector<PropertyDefinition> transformProps = {
    {"position", PropertyType::Vec3, 0, 12},
    {"rotation", PropertyType::Quat, 12, 16},
    {"scale", PropertyType::Vec3, 28, 12}
};

auto result = ComponentSchema::create(
    "CanvasEngine",
    "Transform",
    1,
    transformProps,
    40,
    true  // Public
);

if (result.success()) {
    // Use result.value
}

function computeTypeHash

static ComponentTypeHash computeTypeHash(
    const std::string & appId,
    const std::string & componentName,
    uint32_t schemaVersion,
    const PropertyHash & structuralHash
)

Compute component type hash.

Parameters:

• appId Application identifier
• componentName Component type name
• schemaVersion Schema version number
• structuralHash Structural hash from computeStructuralHash

Return: 128-bit component type hash

Hash = SHA-256(appId || componentName || schemaVersion || structuralHash)

• appId: Application identifier (UTF-8)
• componentName: Component type name (UTF-8)
• schemaVersion: 4-byte uint32 (big-endian)
• structuralHash: 16 bytes (PropertyHash)

This provides a globally unique identifier for the component type.

function computeStructuralHash

static PropertyHash computeStructuralHash(
    const std::vector< PropertyDefinition > & properties
)

Compute structural hash from properties.

Parameters:

• properties List of property definitions

Return: 128-bit structural hash

Uses SHA-256 of concatenated field definitions:

• For each property: name || type || offset || size
• Concatenated in order
• Hashed to 128 bits

Field order matters - reordering fields produces different hash.

function canReadFrom

Result< void > canReadFrom(
    const ComponentSchema & other
) const

Check if this schema can read from another schema.

Parameters:

• other Schema to check compatibility with

Return: Result with error details if incompatible

Returns true if all our properties exist in the other schema with matching types and offsets (subset compatibility).

This is a more expensive O(n*m) check that validates each field. Application decides what to do with the result.

Public Attributes Documentation

variable typeHash

ComponentTypeHash typeHash;

Unique component type identifier.

variable totalSize

size_t totalSize;

Total component size in bytes.

variable structuralHash

PropertyHash structuralHash;

Hash of field layout.

variable schemaVersion

uint32_t schemaVersion;

Schema version for evolution.

variable properties

std::vector< PropertyDefinition > properties;

variable isPublic

bool isPublic;

Whether schema is published for discovery.

variable componentName

std::string componentName;

Human-readable component name.

variable appId

std::string appId;

Originating application ID.

---

Updated on 2026-01-26 at 17:14:35 -0500