Introducing Magic Library Interchange

If you have been interested in magic for any length of time, your library is probably scattered everywhere.

You might have downloads with several different magic dealers, ebooks on your computer, instruction pages protected by passwords, and physical books and tricks spread across a few shelves, or a few rooms.

Each company has built its own downloads library system. That made sense when those systems were created, but it means magicians now have to search several websites and apps simply to remember what they already own.

We think magic can do better.

Today, Vanishing Inc. is publishing version 1.0 of Magic Library Interchange, or MLI: an open standard for describing the items in a magician’s library.

You can read the specification and download the schema at vanishingincmagic.com/schemas.

What is Magic Library Interchange?

Magic Library Interchange is not another library app. It is a shared language that magic shops, publishers and apps can use to exchange information about a magician’s collection.

A participating website can export a customer’s library as an MLI file. Another participating app can import that file without asking the magician to enter every title and creator again.

Instead of an app trying to guess whether two similarly named tricks are the same product, an MLI export contains useful information such as:

• The title
• The creator, author or lecturer
• The original provider
• Whether it is a book, trick, lecture, course or another type of magic
• Whether it is physical, video, ebook, audio or software
• The owner’s relationship with the item
• Public links back to the product or its library page

The result is a small file that a magician can download, keep and import into another compatible service.

Why have we created it?

More apps are being created to help magicians catalogue their collections, build routines, keep practice notes and rediscover material they purchased years ago.

We think that is a positive development.

Those apps should be able to concentrate on creating useful features rather than building a different importer for every magic shop—or asking magicians to type out their entire collection manually. We also believe customers should be able to take a useful record of their library with them.

Making information portable may feel unusual for a retailer, but we think it builds trust. Your magic library represents years of interest, study and investment. It should become more useful over time, not more fragmented.

What does an MLI file contain?

A Magic Library Interchange file contains library metadata: information that identifies and describes each item.

A record can say that a particular product came from Vanishing Inc., that it has a particular product identifier, that it was created by a particular magician, and that it is a video download with permanent access.

Where internationally recognised identifiers exist (such as an ISBN for a book) the format supports those too.

MLI also distinguishes between the company creating an export and the original source of each item. This allows an aggregator to export a library containing products from many different shops without losing their original identities.

At the beginning of every export is a reference to the version of the standard being used:

{
  "schema": "https://www.vanishingincmagic.com/schemas/magic-library/1.0/library.schema.json",
  "format": "magic-library",
  "version": "1.0"
}

The rest of the file contains the library and its individual records.

What does it not contain?

Magic Library Interchange is not a way to transfer secrets or protected content.

An MLI export must not contain:

• Videos, ebooks or other downloadable files
• Instruction passwords
• Private or temporary download links
• Payment information
• Postal addresses
• Customer email addresses
• Complete order records

Importing a library record into another app does not give that app permission to play a video or open an ebook. Access to protected material remains with the company that supplied it.

An MLI file is also not proof of ownership. It is an ordinary file that its owner can open and edit, so it must never be used to unlock protected products.

That separation is central to the standard: portable information, without portable secrets or access credentials.

Why JSON?

Magic Library Interchange uses JSON, a widely supported format for exchanging structured information between applications.

It may not be the most glamorous part of this project, but that is rather the point. A good interchange format should be predictable, well documented and easy for developers to support.

The formal definition of the format is called a schema. It describes every field, which fields are required, what values they can contain and how applications can validate an export.

Alongside the schema, we have published plain-English documentation and example files covering different types of magic products.

Is this a Vanishing Inc. format?

Andi Gladwin and the development team at Vanishing Inc. created and hosts Magic Library Interchange, but it is intended for the entire magic community.

The specification is public, openly documented and royalty-free. Shops, publishers and developers do not need to pay us or ask our permission to implement it. We created this for everyone. A format used only by Vanishing Inc. would simply be a Vanishing Inc. export. but Magic Library Interchange will succeed because independent companies can exchange compatible files.

Version 1.0 has a permanent address. Future improvements will be released as new versions so that integrations built against version 1.0 continue to work.

We will maintain the standard, but we do not want its future to reflect the needs of only one company. Feedback and contributions from other magic stores, developers, publishers, and customers are welcome.

What does version 1.0 support?

The first version has been designed to represent the most common items and relationships found in a magician’s library, including:

• Physical books and ebooks
• Video downloads
• Lectures and courses
• Physical tricks and props
• Products with online instructions
• Software and magic apps
• Subscription content
• Bundles and related products
• Older products without universal identifiers
• Products with multiple creators or contributors

MLI deliberately does not try to standardise everything an advanced library application might record.

Practice logs, routines, performance histories, private notes and the contents of instructional files are outside the core version 1.0 standard. Those areas can be explored later without making the initial format unnecessarily complicated.

What happens next?

Publishing the schema is the first step. The next is adoption.

We will begin using Magic Library Interchange within Vanishing Inc.’s own library systems. We also invite other magic retailers, publishers, and developers to build compatible exporters and importers.

The version 1.0 documentation includes example files that can be used to test an implementation. If two applications can read and preserve the same records without private agreements between their developers, MLI is doing its job.

As the standard is used in the real world, we expect to discover new requirements and unusual products that we have not anticipated. Compatible additions can be made in future minor versions. Any fundamental change will receive a new major version.

Version 1.0 will remain available permanently.

Help us build a more connected magic library

If you operate a magic shop, publishing company, library app or collection-management project, we would love you to support Magic Library Interchange.

If you are a magician with a large collection, ask the services, stores and apps you use whether they plan to support MLI exports and imports.

We are especially interested in hearing about difficult cases: bundles, subscriptions, products that have changed names, multiple editions of the same book, physical products with digital instructions, and items sold by several different dealers.

Magic is an art built on the careful recording, study, and rediscovery of ideas. We think the infrastructure surrounding those ideas should help magicians find and use the material they have collected.

Magic Library Interchange is our contribution toward making that possible.

Explore Magic Library Interchange