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.
Store opaque asset identifiers as strings when they may exceed a browser's exact integer range. Converting a large numeric ID to a JavaScript Number can lose identity before the sprite lookup runs. The file can exist and the JSON can parse successfully while two IDs become indistinguishable.
Key Takeaways
- Treat identifiers as labels unless arithmetic is required.
- Preserve string identity across every serialization step.
- Test round trips near consumer numeric limits.
Valid JSON does not guarantee exact numeric identity
RFC 8259 discusses numeric interoperability between implementations. A producer can emit a number that a particular consumer cannot represent exactly.
JavaScript's Number.MAX_SAFE_INTEGER documentation explains its exact-integer limit. Once precision has been lost, converting the rounded Number to a string does not recover the original identifier.
A sprite ID normally selects a resource; it does not need addition or multiplication. That makes a string a straightforward contract for long opaque identifiers, provided every producer and consumer follows it.
Preserve the identifier at the boundary
Define the field as a string in the manifest and reject numeric input rather than silently coercing it. The JSON Schema string reference documents string constraints. Choose restrictions based on your actual identifier format, not on a guess that every asset uses a particular UUID shape.
Check export scripts, spreadsheets, databases, and browser parsing code. Any intermediate step that converts the label into a number can damage it. Preserve leading zeros when they are part of identity.
Keep frame indexes and counts as separate numeric fields. Changing all numeric fields to strings would obscure useful type distinctions and create a different importer contract.
Example: two neighboring resource IDs
Imagine two exported resource identifiers immediately above a consumer's safe-integer boundary. A browser pipeline parses them as Numbers and builds a lookup map. Distinct original IDs can collapse to the same represented value, so the later record replaces the earlier entry.
The useful test is not whether both JSON documents parse. Verify that their identifiers remain distinct after parsing, mapping, serialization, and reloading. Inspect the final requested texture for each identity.
Use constructed boundary values in a development fixture and label them as such. Do not claim that a real database generated conflicting IDs unless that has been observed and verified.
Repair existing records carefully
Trace where the first precision loss occurs. If the original identifiers still exist in an authoritative source, rebuild the manifest from that source using the string contract. If only rounded values remain, report that identity cannot be reconstructed from them alone.
Update related manifests and caches together so string keys are not mixed with old numeric keys. Record the contract change and test the consumers that depend on it.
This is a mechanism-derived diagnosis and proposed round-trip check. No browser, database, or asset-ID fixture was executed for this article. It does not require a particular identifier scheme; it requires preserving the scheme the project actually uses.
Related workflow
For the adjacent decision, see sprite asset version manifest cache handoff. 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)