JSONM Interchange · Developers Hub

JSONM is the portable design-system interchange format used by MyronCMS. A .jsonm file is standard JSON, but it must satisfy the MyronCMS style-definition schema, token-map vocabulary, validation rules, and design-system semantics.

The current MCP resource for interchange guidance is:

mcp://myroncms/design/jsonm-interchange

Use it before generating, translating, or importing a JSONM document. The resource is composed by the running install and includes live token-map examples and a current install example.

Human Path

A design system author can use the current API loop:

Export the active design system.
Translate or edit the JSONM with an external design workflow.
Validate that the result still matches the schema and token map.
Import the JSONM envelope.
Optionally apply the imported definition when that is the intended operator action.

The export endpoint returns structured JSON:

GET /api/v1/design/definitions/export-current

The import endpoint accepts a JSON-content envelope:

POST /api/v1/design/definitions/import

The import payload includes filename, contentType, contentBase64, sizeBytes, sha256, and optional importName and applyImmediately.

AI Path

An MCP client can read mcp://myroncms/design/jsonm-interchange to learn the exact document shape and translation rules for the running install.

An AI integration with design.read can discover and call the export action when exposed through tools/list. An AI integration with design.write can discover and call the import action when exposed through tools/list.

An AI coding agent working locally can also run repository verification:

php app/tests/verify-jsonm-interchange.php

Scopes

Runtime entrypoint	Scope
`mcp://myroncms/design/jsonm-interchange`	No action scope in the current resource list.
`GET /api/v1/design/definitions/export-current`	`design.read`
MCP tool for export-current	`design.read`
`POST /api/v1/design/definitions/import`	`design.write`
MCP tool for import	`design.write`

Artifacts

Primary source contracts:

app/system/mcp/Server.php
app/api/actions/design/ExportCurrentDefinitionAction.php
app/api/actions/design/ImportDefinitionAction.php
app/jsonm/schema/style-definition.schema.json
app/jsonm/maps/token-map.json
dev-references/jsonm-spec/jsonm-specification.md

Runtime data and verification:

app/jsonm/current-definition.json
app/jsonm/baselines/
app/jsonm/archetypes/
app/tests/verify-jsonm-interchange.php

JSONM Shape

A current JSONM v1 style definition includes:

Field	Current requirement
`schemaVersion`	Must equal `"1"`.
`format`	Must equal `"JSONM"`.
`kind`	One of `baseline`, `named`, or `preset`.
`id`	Non-empty definition id.
`name`	Human-readable definition name.
`corpus`	Bound to the current design corpus.
`settings`	WCAG policy and appearance mode behavior.
`tokens`	Complete token payload for mapped token families.
`fontRoles`	Font role assignments for headlines, subtitles, body, UI, and micro text.

The token payload is not open-ended. The token map defines which JSON paths map to which CSS custom properties, and validation rejects missing mapped paths.

Safety Boundary

Do not treat JSONM as a loose theme blob. A valid document must be standard JSON, schema-conformant, token-map complete, and acceptable to the import validator.

Do not invent new token families or token paths in documentation or generated examples unless a later contract expands the schema and token map.

Do not use applyImmediately casually. Importing and applying are separate product actions because applying design state changes the rendered site.

Do not bypass WCAG contrast validation. Contrast failures are design failures, not parser inconveniences.

Verification

Run:

php app/tests/verify-jsonm-interchange.php

The verifier asserts that:

export-current returns a valid JSONM payload,
mcp://myroncms/design/jsonm-interchange is listed and readable,
the interchange document covers required spec sections,
exported JSON survives a round trip through JSON encode/decode,
export and import actions are registered and MCP-exposed.

For an MCP client, also verify:

resources/list includes mcp://myroncms/design/jsonm-interchange
resources/read returns text/markdown for that URI
tools/list includes the export/import tools only when caller scopes allow them

Failure Modes

Failure	Likely cause	Safe response
Import returns `input_invalid`	JSON-content envelope is malformed, base64 is bad, or metadata does not match content.	Rebuild the envelope with correct `contentBase64`, `sizeBytes`, and `sha256`.
Import returns `precondition_failed`	JSON parses but fails product or validation rules.	Re-read the interchange resource and fix schema, token, or contrast issues.
Token path is rejected	Path is not in the current token map or required paths are missing.	Use `mcp://myroncms/design/jsonm-interchange` and `app/jsonm/maps/token-map.json` as authority.
Export tool is missing from MCP `tools/list`	Caller lacks `design.read` or action exposure changed.	Use a correctly scoped caller and verify action metadata.
Import tool is missing from MCP `tools/list`	Caller lacks `design.write` or action exposure changed.	Use a correctly scoped caller and verify action metadata.
Imported design changes live output unexpectedly	Import was applied immediately or the wrong definition was selected.	Keep import and apply decisions explicit and operator-reviewed.