Canonical Unit

The canonical unit is the fundamental object of the NexArt protocol. Every system executed, stored, or transmitted through NexArt is represented as a canonical unit. This page defines what it is, what it contains, and what it intentionally excludes.

The canonical unit is application-independent. The protocol, not the user interface, defines system meaning.

Definition

A canonical unit is a complete, portable specification of a deterministic system. It contains everything required to reproduce the output of that system, and nothing more. Reproducibility requires a determinism declaration and resolvable external references when used.

The canonical unit is mode-agnostic. Whether a system was authored using SoundArt, Code Mode, Shapes, or any other creation primitive, it is represented in the same fundamental structure.

What It Contains

The protocol requires every canonical unit to include:

• Mode identifier, which creation primitive produced the system
• Parameters, the complete set of values that define the system’s behavior
• Protocol version, the protocol version this system conforms to
• Determinism declaration, whether the system is deterministic or best-effort
• External references, pointers to any required assets such as audio files or images

What It Does Not Contain

The protocol requires canonical units to exclude:

• Rendered outputs, images, videos, or other artifacts derived from the system
• Implementation details, how a particular renderer or tool processes the system
• User interface state, view settings, window positions, or other ephemeral data
• Authentication or access control, ownership and permissions are handled externally
• Embedded binary assets, external references are used instead to keep units portable

Why This Abstraction Exists

The canonical unit serves several purposes:

Portability. A canonical unit can be moved between tools, platforms, and storage systems without loss of meaning. It is self-describing and self-contained.

Verifiability. Because the unit includes parameters and declarations, completeness can be checked. A renderer can validate that it has everything needed before execution.

Durability. By excluding rendered outputs and implementation details, the canonical unit preserves what matters long term, the rules that define the system.

Interoperability. Different tools can read and write canonical units even when their renderers and interfaces differ.

Mode Conformance

The protocol requires all creation modes in NexArt to produce canonical units. Implementations are being migrated to conform to this requirement. Modes differ in how systems are authored, but they converge on a shared representation so that systems can be stored, shared, and processed uniformly.

Current Status

The canonical unit structure described here represents the protocol requirements. Implementations are being migrated to fully conform to this specification. Some implementations may store additional data alongside the canonical unit during the transition period.

Serialization

The protocol does not mandate a specific serialization format. Implementations may use JSON, binary formats, or other representations, as long as they can round-trip a canonical unit without loss of information.

Reference implementations may be provided separately.