Hi Lucid Developers! 

Since the launch of our JSON Import functionality, we've seen an array of creative and efficient uses by our customers. In this post, we'll address some of the most frequently asked questions about the JSON Import feature. Additionally, we’d like to announce expanded functionality based on your valuable feedback: support for adding notes to shapes via the API! 

Adding notes to shapes 

You can now add notes to shapes, groups and layers by including a note field in your shape properties. For more information on how to do this, feel free to check out our documentation here!

JSON Import API FAQs 

Q: Is the JSON import asynchronous? How will I know when the import is complete?
No, it is actually synchronous. When the request is returned, the document is complete.

Q: Is z-order for an entity based on array position? Last-on-top or first-on-top? (Does this mean lines are already "on top" of shapes, since it is a separate array?)

In Lucid's JSON structure, z-order refers to the visual stacking order of entities on the canvas. The positioning of an object in the JSON array directly affects its z-order. Objects defined later in the JSON appear "higher," meaning they are rendered on top of objects defined earlier.

The current version of our API does have one limitation: either all shapes must be on top of all lines, or vice-versa. This is because all lines are defined in a single array and all shapes in another. Adding a shape or a line to a group may also impact z-order.
 

We decided to not include more granular controls for z-order in our initial release of the API. If there is interest or a need for such controls, please let us know here.

Q: I see there are limits on the size of the /images and /data folders. Is there a cap on the size of the document.json file, or the .lucid file?

Yes, 1.5 MB for a document.json file, 50 MB for a .lucid file.

Q: Could I make a diagram so complicated that it crashes the import?

The 1.5 MB limit is intended to avoid making documents so complex that it crashes the import. Although documents do function at max size in our testing, the closer you get to 1.5 MB, the worse the document will perform. Also note that our API doesn't exclude whitespace when determining whether the JSON payload is too large, so you can cram more objects in by minify-ing your json.

Q: Can my JSON include shapes in the Lucidspark library when importing as a Lucidchart document (and vice versa)?

We actually don't limit any shapes or objects by product. Lucid is really interested in a "Universal canvas", where the editors/chrome/UI for the products are different, but the canvas objects themselves are usable by any Lucid editor.

We hope you found these answers helpful! If you have any additional questions, don’t hesitate to post them in the thread below.