Schemas & Canonicalization

ENTITY uses versioned schemas and deterministic serialization so signatures and hashes mean the same thing across implementations. Equivalent-looking but differently serialized records must not be treated as interchangeable unless the applicable protocol version says they are.

Canonical JSON

The identity runtime canonicalizes JSON with sorted keys, compact separators and UTF-8 encoding before hashing/signing. Implementations must reproduce the protocol-defined canonical form byte-for-byte before comparing hashes or signatures.

Schema versioning

Every durable protocol object should identify its schema/version. A parser must reject unknown required semantics rather than silently guessing. Historical signed records retain the schema semantics under which they were issued.

Hash boundaries

Document exactly what bytes or canonical object are hashed. For release evidence, distinguish the Git commit SHA-1, Git tree SHA-1, SHA-256 of release sidecars/manifests, semantic roots and content hashes. They answer different integrity questions and are not substitutes for one another.

Signature boundary

A signature verifies the canonical payload/record that was actually signed. It does not sign surrounding UI text, external database state or an unstated interpretation. Include key ID, suite and payload digest where the signature-record schema requires them.

Compatibility rule

Do not retroactively reinterpret old signed bytes under new semantics. If a schema/profile changes, issue a new version or migration/derivation record and preserve the earlier signed object.

Independent implementation

Clean-room implementations should parse schemas, canonicalize, hash and verify signatures without importing BTG runtime code. Reaching the same accept/reject result on sealed vectors is one of the key interoperability proofs.