Canonical Structure Policy

This policy defines the requirements for Elonn canonical structures.

Canonical Structures

Canonical structures are the shared data structures used across Elonn Component boundaries.

They provide a common representation of platform concepts without requiring one Component to depend on another Component's internal data model or implementation.

A structure SHOULD be canonical when consistent interpretation of that structure is required across Component boundaries.

A structure used only within one Component or implementation does not need to be canonical.

Canonical Publication

Canonical structures are maintained and published under:

dev.elonn.com/public/canonical/

Each canonical structure SHALL have:

<structure>.json
<structure>.md

For example:

call.json

dataset.json
dataset.md

object.json
object.md
```

There SHALL be one authoritative definition of each canonical structure.

JSON

<structure>.json

The JSON artifact is the normative definition of the canonical structure.

It SHALL define the structure sufficiently for machine interpretation and validation, including its fields, types, requirements, and constraints.

Where the JSON and Markdown artifacts disagree, the JSON artifact governs.

Markdown

<structure>.md

The Markdown artifact is the human-readable description of the canonical structure.

It SHALL describe the purpose, semantics, fields, requirements, and relationships represented by the JSON definition.

It SHALL describe rather than independently redefine the normative JSON structure.

Design

A canonical structure SHALL:

• represent a shared platform concept;
• have a single defined meaning;
• use stable and descriptive names;
• define required and optional fields;
• define the meaning of its fields;
• reference other canonical structures rather than redefine them;
• remain independent of Component implementation details.

A canonical structure SHOULD be no larger or more complex than required to represent its platform concept.

Use

Components and Service contracts SHALL reference canonical structures rather than maintain independent copies or definitions.

Service-specific structures MAY be defined when the represented concept is specific to that Service.

A Service-specific structure SHOULD become canonical when it becomes a shared platform concept requiring consistent interpretation across Component boundaries.

Evolution

Canonical structures are platform-wide dependencies.

Changes SHALL preserve existing meaning and compatibility where practical.

A change that alters the required meaning or interpretation of a canonical structure SHALL be treated as a change to the canonical structure itself, not as a local Component or implementation change.

Invariant

A canonical structure has one authoritative definition under canonical/.

Components exchange canonical structures.

Components do not redefine them.