ENTITY Documentation Portal
Developer manual · ENTITY v3.4.3 · deterministic semantics

Schemas & Canonicalization

Target boundary: runtime documentation here uses ENTITY v3.4.3. Frozen Protocol 1.0 conformance and historical v3.4.2 evidence remain separate targets and must retain their own exact schemas, vectors and hashes.

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 schema/protocol version explicitly defines them as such.

Canonical JSON

The identity/runtime code canonicalizes JSON with sorted keys, compact separators and UTF-8 encoding before hashing/signing. Implementations must reproduce the applicable 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 semantics under which they were issued.

Hash boundaries

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

Signature boundary

A signature verifies the canonical payload/record 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.

Protocol 1.0 versus runtime release

Protocol 1.0 is the frozen external conformance target. ENTITY v3.4.3 is the current supported runtime release. A conforming Protocol 1.0 vector result and a v3.4.3 runtime regression result may both be valid while describing different test targets.

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 the applicable sealed vectors is one interoperability proof; it is not automatically a security certification or market/deployment validation.