Catalogue Ingest API

Share semantics

Four different share values. Never copy one into another.

This page describes four percentages. They look interchangeable. They are not. Copying one into another produces a registration that pays the wrong party, and that is expensive to undo.

The four values#

Value	Field	What it means
Work ownership	`writer_ownership_pct`	The writer's share of the underlying work.
Mechanical collection	`publisher_collection_share`	What the publisher collects on mechanicals. This is the MLC value.
Performance collection	`publisher_pr_share`	What the publisher collects on performance.
Recording ownership	`master_share`	Ownership of the master recording, not of the work.

A worked example#

A writer owns 50% of a work. Their publisher collects 25% of the mechanicals on it.

json

{
  "writers": [
    { "writer_first_name": "Alex", "writer_last_name": "Stone", "writer_ownership_pct": 50 }
  ],
  "publishers": [
    { "publisher_name": "Acme Publishing", "publisher_collection_share": 25, "linked_writer_index": 0 }
  ]
}

Both numbers are correct, and they differ. Do not set the publisher share to 50 because the writer owns 50.

Where each value goes#

Different destinations read different values. This is why we keep them apart.

Destination	Reads
MLC, column P	`publisher_collection_share`
Musicmark EBR, writer columns	`writer_ownership_pct`
SoundExchange, "Percentage Claimed"	`master_share`

If you hold only one#

Send the one you hold. Leave the other out.

We flag the missing value as a gap, and you can fill it later. Do not guess it, and do not copy across the value you do have. A gap is a known unknown. A wrong number looks like fact.

Scale and validation#

All four use a 0 to 100 scale. 50 is 50%. 1 is 1%. A value outside that range returns 400.

We store shares as fractions, so 50 becomes 0.5. The conversion is lossless. It only changes how the value looks in downstream systems.

We check totals and report them in the validation block:

Code	Meaning
`writer_share_over`	Writer ownership shares add up to more than 100%.
`collection_share_over`	Publisher collection shares add up to more than 100%.

Neither blocks the write. Both mean somebody must look at the work.