Skip to content

Catalog import

The catalog import brings a client’s catalog sheet into emely. You map the sheet into one JSON document; emely validates it, matches every item against the catalog it already holds, shows you the plan, and applies only the plan you approved. All import tools require an operator token - sign in through OAuth as an operator. A personal access token is always api_user and cannot call them.

  1. describe_import_format returns the format contract: the JSON Schema, its schemaSha256, the limits, the mapper guidance, and the vocabularies.
  2. start_import_draft opens a draft in the target workspace and returns a draftId. source is required: pass fileName or description to name the import, because every row it writes carries that source.
  3. add_import_draft_part uploads the document section by section, in parts of at most 64 KB each.
  4. dry_run_import assembles the parts, validates the document, matches its items against the catalog, and stores a plan. Nothing is written to the catalog.
  5. get_import_plan reads the stored plan’s report, one page per call.
  6. apply_import_plan executes the stored plan.

The format is emely-catalog-import, formatVersion: 1. A document is:

{
"format": "emely-catalog-import",
"formatVersion": 1,
"source": {"fileName": "…", "mappedBy": "…"},
"parties": [],
"works": [],
"recordings": [],
"products": [],
"unmapped": []
}

Items reference each other by a local ref, unique within its section. Every item may carry sourceRow ({sheet, row}) so the report can point back at the source sheet. unmapped holds {ref?, field, value, sourceRow?} entries: every source value that has no place in emely. Unmapped values land in the claim’s raw payload and in the report; they are never read as data.

The describe_import_format response carries the JSON Schema verbatim plus schemaSha256, the hash of the schema the backend validates against. If the hash the dry run reports differs from the one you described, re-read the format before mapping further.

Roles, kinds, genres, languages, configuration kinds, vinyl sizes and speeds, surround formats, music types, recording types, audio presentations, bit depths, sample rates, channel configurations, immersive formats, content kinds and external systems take values from the vocabularies the format response lists. Never invent a vocabulary value. A source value with no exact match goes to unmapped with its sourceRow. Vocabulary items are returned in alphabetical order.

Map a sheet’s text by name, send the code. Genres are Apple codes: genres items carry {code, name, groupCode, sortOrder} and a sheet’s “Pop” maps by name to POP-00. Roles use the vocabulary slugs: performer-roles, studio-roles and work-writer-roles items carry {value, name, sortOrder} and “Lead Vocals” maps by name to lead_vocals. The import’s own match on what you send stays exact and case-sensitive.

The import vocabularies are also readable through list_reference_values with an operator token: artist-kinds, artist-credit-roles, performer-roles, studio-roles, work-writer-roles, title-kinds, languages, genres, music-types, product-kinds, configuration-kinds, vinyl-sizes, vinyl-speeds, surround-formats, recording-types, recording-track-kinds, audio-presentations, audio-bit-depths, audio-sample-rates, audio-channel-configurations, immersive-audio-formats, language-content-kinds, external-systems.

Send identifiers exactly as the source states them, check digits included. ISWC, ISRC, ISNI, IPI name number, UPC and the other identifier fields are validated, including check digits. Every identifier an import writes becomes locked as imported, so map an identifier only when the sheet is sure of it.

Two traps from real sheets: a column labeled “IPN” usually holds IPI name numbers (map those to ipiNameNumber), and UPCs can lose leading zeros in a spreadsheet - send the full 12- or 13-digit code.

  • Leave a field out rather than fill a default. Absent means “not stated”: on a matched item the current value is kept, on a created item the column default is taken. null is refused everywhere.
  • Never split or merge people by guessing. One credited name is one party; two spellings may share a ref only when an identifier agrees.
  • A legal name and the identifiers next to it go to the party’s person block: firstName, middleName, lastName, ipiNameNumber, isni. The party’s own isni and ipiNameNumber stay the stage/credit ones - the two blocks are distinct columns. A group (band, ensemble_orchestra) takes no person. When a writer row states a legal name, match it to the credit-name party by IPI and put the legal data in person; when a legal ISNI or IPI disagrees with what emely holds, the report lists it as a secondary ISNI candidate for the operator - the import never stores it itself.
  • A work needs its ISWC. A recording whose work has no ISWC is sent without work; the work’s writers go to unmapped with the recording’s ref.
  • Lists add and enrich, never remove. The import never deletes a row that is already there.
  • One isMain per list (genres, audio languages). Credits dedupe on (party, role).
  • A “Composer and Lyricist” writer credit is two entries: one composer and one lyrics on the work, for the same party. The vocabulary has no combined value for both.
  • Arranger credits on a recording are studio roles: map them to recording_arranger, orchestrator or studio_arranger by the credit’s scope. The work-writer arranger is a role on the work itself, not on its recordings.
  • One release in several formats is one product with one configuration per format.

A pLine or cLine is {year, owner, extension?}. Year and owner make the line; extension is an addition appended after the owner, never the line itself. An audio recording carries pLine and no cLine; a video recording carries cLine and no pLine. A product may carry both pLine and cLine.

The fields mean, per level:

  • Recording (audio) pLine.year: The year the sound recording was first ever released. pLine.owner: The original rights owner of the sound recording. pLine.extension: Identifies who currently represents or administers the rights in the sound recording, e.g. “under exclusive license to Label A” or “distributed by Label B”. Leave blank if no additional notice is required.
  • Product pLine.year: The year this product was first released. pLine.owner: The original rights owner of this product. pLine.extension: Additional information about a licensee, distributor or other party associated with this product, e.g. “under exclusive license to Label A” or “distributed by Label B”. Leave blank if no additional notice is required.
  • Product cLine.year: Identifies the year of first publication of the copyrighted material (such as cover artwork, liner notes, and packaging design). cLine.owner: The original rights owner of the copyrighted material (such as cover artwork, liner notes, and packaging design). cLine.extension: Additional information about a licensee, distributor or other party associated with this product, e.g. “under exclusive license to Label A” or “distributed by Label B”. Leave blank if no additional notice is required.
  • Video cLine.year: Identifies the year of first publication of the audiovisual work (video). cLine.owner: The original rights owner of the audiovisual work (video). cLine.extension: Additional information about a licensee, distributor or other party associated with this video, e.g. “under exclusive license to Label A” or “distributed by Label B”. Leave blank if no additional notice is required.

Upload each section in parts: add_import_draft_part takes {draftId, section, part, items}, where section is one of parties, works, recordings, products, unmapped and part is a 1-based index within the section. Each part is at most 64 KB. Resending the same {section, part} replaces it, so a mapper can fix and resend one slice without restarting. Keep refs stable across re-sends: other parts may point at them.

The limits are part items ≤ 64 KB, assembled document ≤ 2 MB, and at most 5000 items across the document. start_import_draft returns them and describe_import_format repeats them.

dry_run_import returns the plan’s status, its planId, the schemaSha256 it validated against, totals, bound, and reportPages. A dry run writes nothing to the catalog; it stores the plan. bound counts refs bound to an earlier applied plan of the same draft.

The status is reported in-band on a 200, not as an HTTP error. On busy another call holds the draft’s lease - wait and retry. On invalid the document failed validation - read errors, fix the mapping and resend the parts. get_import_plan can report stale when the draft changed after the plan was stored - dry-run again. apply_import_plan reports applied when every unit committed, partial when the call’s time box ran out with remainingUnits left (call apply again to resume), applied_with_failures when the plan finished but some units failed or were blocked (read failedUnits, blockedUnits and droppedOps; a repeat call reports the same verdict), busy when the draft lease is held by another call or was lost mid-run (wait and retry), stale when the draft’s parts changed since the dry run (dry-run again) or already_applied when a repeat call wrote nothing.

When an item’s identifiers match several existing rows, the item comes back in ambiguous with its candidates. Resolve each one and call dry_run_import again with matches: "section:ref" mapped to an existing row id, or "new" to create it. Never answer new for an item an identifier found - that is refused.

get_import_plan returns one report page per call along with page and pages. Read every page before applying: the report is the record of what will be written.

A draft can be dry-run and applied more than once. A later dry run binds the refs an earlier applied plan already resolved (bound) and compares the document against the state that earlier apply left, not only against the live rows. Anything changed by hand after the earlier apply is kept and listed, never silently reverted:

  • a field changed after the import: kept: changed after the import
  • a credit, writer or other child removed after the import: kept: removed after the import - the row is not re-added
  • a configuration moved to another product after the import: kept: moved after the import
  • an artist, person or recording merged into another row: the item follows the merge (followed merge)
  • a value the revised sheet changes on an untouched row: written (updated)

A row the earlier import never touched keeps the plain overwrite semantics: a revised value replaces the live one.

apply_import_plan executes the stored plan and returns the applied units, any units that failed, were blocked or went stale, and the operations that were dropped. Applying the same plan again creates no new claims, so a repeat call is safe. Every write lands with its provenance claim; a claim that loses all of its writes is dropped rather than left claiming a row that does not exist.