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 ceiling#

All four values are shares of the whole work, on a 0 to 100 scale. 50 is 50%. 1 is 1%. A value outside that range returns 400.

A publisher row is bounded by the writer it is linked to. Collection is at most that writer's ownership. Performance is at most half of it, because a society pays the other half to the writer direct. The bound is per row, on the work scale. It is not a share of "the publisher's half".

Scenario	Party	`writer_ownership_pct`	`publisher_collection_share`	`publisher_pr_share`
One writer, self-published	W1 / W1's publishing entity	100	100	50
Two equal writers, each self-published	W1 / P1	50	50	25
	W2 / P2	50	50	25
One writer, third-party administrator	W1	100
	P1, administrator		100	50

A publisher linked to a writer at 50 sends collection 50 and performance 25 percent. A performance share of 100 percent on that row is over the ceiling. It is the most common error we see.

Validation#

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.