You have a reference to an object, maybe found by filtering the list based on co-ordinate intersection, and you need its ID to put somewhere else (e.g. in the "to" field of an edge). Sure, all your find/filter methods could return (ID, object) or just return an ID and make you do a second lookup to find the object, but at the kind of object counts we're talking about for this implementation, a small amount of extra memory to have the ID as a field in exchange for a nicer API is a reasonable tradeoff.

Looking at their reference impl, it does seem that array index implies z-index, in which case fair enough, I suppose an array does make the most sense - they should probably document the z-indexing though!

Sometimes you have nodes that overlap each other, so you want to control whether or not a node is in front of or behind another node.

Though yes, they could have explicitly defined a z-index or defined a convention on how the ordering should work (first nodes top and last nodes bottom or vice versa?). It's interesting to think about the trade offs between explicitly defining these things vs. leaving the application to implicitly make the choice. JSON Canvas seems to be designed to use in tandem with markdown files in a note taking app, so it makes sense why they opted for the more implicit design to be similar to markdown

This clarification has been added to the spec:

> Nodes are placed in the array in ascending order by z-index. The first node in the array should be displayed below all other nodes, and the last node in the array should be displayed on top of all other nodes.