Magic Library Interchange 1.0

1. Purpose and scope

MLI lets a customer export a metadata snapshot from one service and import it into another. It is designed for retailers, publishers, library apps, collection managers, and aggregators. An MLI file describes a library; it is not proof of purchase and does not grant access to protected content.

2. File and schema

A conforming file is UTF-8 JSON and validates against JSON Schema Draft 2020-12. Its top-level schema property must contain the immutable URL for the version it implements. This complete minimal example describes Ed Marlo's Cardially Yours as a physical book:

{
  "schema": "https://www.vanishingincmagic.com/schemas/magic-library/1.0/library.schema.json",
  "format": "magic-library",
  "version": "1.0",
  "export_id": "735af9ce-78bb-4b38-9d01-ae97d9f260dd",
  "exported_at": "2026-08-23T12:00:00Z",
  "exporter": {
    "id": "vanishingincmagic.com",
    "name": "Vanishing Inc. Magic",
    "url": "https://www.vanishingincmagic.com"
  },
  "items": [
    {
      "source": {
        "provider": "vanishingincmagic.com",
        "item_id": "cardially-yours"
      },
      "title": "Cardially Yours",
      "contributors": [
        {
          "name": "Ed Marlo",
          "role": "author"
        }
      ],
      "kind": "book",
      "formats": [
        "physical"
      ],
      "language": "en",
      "holding": {
        "relationship": "owned",
        "quantity": 1
      },
      "links": [
        {
          "rel": "catalog",
          "href": "https://www.vanishingincmagic.com/card-magic/cardially-yours/"
        }
      ]
    }
  ]
}

The export's schema value is different from the JSON Schema document's $schema dialect declaration and its canonical $id.

3. Stable item identity

Importers identify an item using source.provider + source.item_id + the optional source.variant_id. The provider is a stable, DNS-style namespace controlled by the source. Aggregators must preserve this original identity when they re-export a record.

Re-importing the same identity should update or merge the existing record, not create a duplicate. ISBN, GTIN, UPC, and other identifiers can aid matching, but they do not replace source identity.

4. Library items

Every item requires a source, a non-empty title, and a holding. The remaining fields add detail when the exporting service knows it:

• contributors records people or organizations as creators, authors, lecturers, instructors, performers, editors, illustrators, translators, producers, publishers, manufacturers, or other contributors.
• kind describes the work: trick, book, magazine, lecture, prop, deck, app, or other.
• formats describes physical, hardback, softback, ebook, video, audiobook, app, or other editions held by the customer.
• access_methods records whether digital material is available by download or stream.
• identifiers carries public catalogue identifiers.
• language is a BCP 47 language tag.
• links contains only durable public catalogue, cover, or account-access pages.
• extensions holds namespaced provider-specific metadata.

5. Holding semantics

holding.relationship says whether an item is owned, licensed, subscribed, borrowed, or unknown. The optional acquisition date uses an RFC 3339 date-time string. An export is a user-editable snapshot, so an importer must never treat it as authoritative proof of ownership or entitlement.

6. Privacy and security

An MLI export must not contain:

• passwords, credentials, tokens, or signed URLs;
• instructional files or the contents of protected media;
• customer email, address, contact, or payment details;
• private notes, routines, practice logs, or performance history.

7. Importer behavior

• Validate the document before importing it.
• Reject unsupported major versions.
• Ignore unknown fields for forward compatibility.
• Use stable source identity to make repeated imports idempotent.
• Treat links and extensions as untrusted input and never execute their contents.

8. Versioning policy

Released schema URLs are immutable. Backwards-compatible additions receive a new minor version. Breaking changes receive a new major version. Exporters must point to an exact versioned schema URL and must not use a moving latest URL.

Changelog

1.0 — 23 August 2026: first stable release.

9. Licence

The MLI 1.0 specification and schema are dedicated to the public domain under CC0 1.0. They may be implemented without charge or permission.