Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Define an unknown-field policy before an older importer receives a newer sprite manifest. Reject changes that affect interpretation, while allowing clearly isolated optional metadata only when the contract permits it. Silently ignoring every unfamiliar field can produce a visually plausible but incorrect import.
Key Takeaways
- Separate required rendering semantics from optional annotations.
- Specify the schema dialect and importer capability together.
- Test old consumers with explicit future-field examples.
Unknown does not always mean optional
The JSON Schema object reference explains properties, required fields, and additional-property behavior. Merely listing known properties does not automatically reject every other property.
A metadata field can be harmless, such as an internal review note. Another can change frame interpretation, such as rotation, trimming, or a new coordinate convention. Treating these equally makes forward compatibility unsafe.
Split the project-owned contract
For a manifest format you control, define a small core containing everything required to render the asset correctly. Put optional annotations into a documented extension area. State whether unknown extensions may be ignored and how mandatory capabilities are declared.
Use enumerated values for bounded choices such as an origin convention. Avoid silently interpreting an unknown mode as the first known mode. If a renderer cannot support the requested semantics, it should reject that candidate or request a compatible export.
Remember that JSON syntax does not establish application meaning. A parsed object can be perfectly valid JSON while requiring a feature the importer does not implement.
Example: a newly trimmed atlas
An older importer assumes every frame occupies its original cell. A new exporter adds trim offsets and smaller frame rectangles. If the old importer ignores offsets, each image can decode correctly while the character jumps between poses.
The required change is not to allow all new fields. Either export the older fixed-cell contract or update the importer to implement trimming and its coordinate rules. An optional review-comment field, by contrast, need not force the same incompatibility response.
Record both cases as proposed contract tests. The first should fail clearly in the older consumer; the second may pass only if optional extensions are explicitly supported. Do not claim those outcomes were tested until the actual importer has run.
Acceptance and migration
Create examples for a missing required field, unknown optional extension, unsupported semantic mode, and incorrectly typed value. Review error messages so artists can distinguish a malformed manifest from a consumer-capability mismatch.
Maintain the schema version and supported capability list alongside the importer. Changing a schema file alone does not add rendering support. If you use a third-party atlas format, follow its contract rather than inventing conflicting rules around its fields.
Accept the migration when the intended old and new consumers handle each example as documented and the rendered placement matches the approved source. This article proposes a project-contract design; it is not an engine compatibility test or a guarantee that arbitrary future fields are safe.
Related workflow
For the adjacent decision, see ldtk jsonversion schema importer capability check. Carry the animation handoff checklist with the release and retain the art reference board for visual decisions.
Prepared by the FrameSprite Workflow Team. Editorial method · Corrections. Primary documentation checked 2026-10-20.
Top comments (0)