Parties and credits

A party is a person or organization: an artist, a label, a producer, a publisher. A credit connects a party to a release or a track in a DDEX role — MainArtist, Producer, Composer.

Release-level credits (the billing artist, the label) and track-level credits (who played and produced each recording) are kept separate, because they genuinely differ — on a compilation, especially.

Labels also appear as Label on each release, and labels lists every label in your catalog.

Operations

querylabels
mutationcreateParty
mutationcreditRelease
mutationcreditResource
mutationremoveReleaseCredit
mutationremoveResourceCredit

The Party object#

A person or organization — an artist, label, producer, writer or publisher.

Attributes

partyPkInt!
Unique identifier. The same party credited on two releases has the same partyPk.
dpidStringnullable
DDEX Party Identifier, when supplied. Many individual performers have none.
nameStringnullable
One name, preferring the one the sender marked default. When a party has names in several scripts and none is marked default, which one you get is arbitrary — use names whenever the script matters.
names[LocalizedText!]!
Every name this party carries, in every language, script and territory.
Arguments
- typeString
  Only variants of this text type, e.g. DisplayTitle or FormalTitle. Case-insensitive.
- languageString
  Only variants whose language tag is exactly this, e.g. ja-Jpan or ja-Latn. The whole tag, not a prefix: ja does not match ja-Jpan. Use script to select by script alone.
- scriptString
  Only variants in this ISO 15924 script, e.g. Jpan or Latn.
- territoryString
  Only variants that apply in this territory, e.g. US: variants scoped to it, plus unqualified variants where nothing more specific exists. See Territories and languages.
- isDefaultBoolean
  Only variants whose default flag matches. Many senders flag none as default, so true can legitimately return an empty list.

The Party object

{ "partyPk": 90450, "dpid": null, "name": "Halfway Ghosts" }

The Credit object#

One party credited in one role.

Attributes

partyParty!
The credited party.
roleStringnullable
The DDEX role exactly as delivered — MainArtist, StudioProducer, Composer, …
roleKindStringnullable
Which vocabulary the role came from: DisplayArtistRole for billing, ResourceContributorRole for people who worked on the recording. Filter on this rather than guessing from the role's spelling.
territoryStringnullable
The territory the credit applies to. null means unqualified, which is not the same as Worldwide.
sequenceIntnullable
Billing order, when the sender gave one.

The Credit object

{
  "party": { "partyPk": 90450, "name": "Halfway Ghosts" },
  "role": "MainArtist",
  "roleKind": "DisplayArtistRole",
  "territory": null,
  "sequence": 1
}

The Label object#

A label a release came out on. A label is a Party, so every release on the same label shares its partyPk.

Attributes

partyPkInt!
The label's party id — the same on every release on this label.
nameStringnullable
The label's default name.
dpidStringnullable
DDEX Party Identifier, when the sender supplied one.
labelTypeStringnullable
DisplayLabel or UserDefined when the sender said; usually null.
territoryStringnullable
The territory this label applies to. null means unqualified, not Worldwide.
isDefaultBoolean!
Whether the sender marked this label as the default.
sequenceIntnullable
The order the message listed labels in.

The Label object

{
  "partyPk": 90211,
  "name": "Lanternfish Records",
  "dpid": "PADPIDA2014120301H",
  "labelType": null,
  "territory": null,
  "isDefault": true,
  "sequence": 1
}

The LabelSummary object#

A label in your catalog and how many releases it has.

Attributes

partyPkInt!
The label's party id.
nameStringnullable
The label's name.
dpidStringnullable
DDEX Party Identifier, when known.
releasesInt!
Number of distinct releases on this label, not counting drafts or blocked deliveries.

The DraftParty object#

A party as returned by createParty.

Attributes

partyPkInt!
Unique identifier. Use it in CreditInput.
nameString!
The name, trimmed.
dpidStringnullable
The DPID, if given.

The CreatePartyInput input object#

A party to create.

Fields

nameString!required
The party's name. Required and must not be blank.
dpidString
DDEX Party Identifier. If a party with this DPID already exists in your catalog, that party is returned instead.
nameTypeString!Default: "FullName"
The DDEX name type.

The CreditInput input object#

A credit to add.

Fields

partyPkInt!required
The party to credit, from createParty or an existing credit.
roleString!required
The DDEX role, e.g. MainArtist, Producer, Composer. Not Label — a label is set with labels on createRelease or updateRelease, and a Label credit is refused.
roleKindString!Default: "DisplayArtistRole"
The vocabulary role belongs to. DisplayArtistRole for release billing; ResourceContributorRole for track contributors.
territoryString
Leave unset unless the credit really applies to one territory only. Unset is not the same as Worldwide.
sequenceInt
Billing order.

The LabelInput input object#

A label to put a release out on, in labels.

Fields

partyPkInt!required
The label, from createParty. The same party on every release keeps them together under one label.
labelTypeString
DisplayLabel or UserDefined. Usually left out.
territoryString
Leave unset unless the label applies to one territory only — a reissue can carry a different label per territory. Unset is not the same as Worldwide.
sequenceInt
Display order when there are several.
isDefaultBoolean!Default: false
The default among several. At most one; when none is marked, the first is.

List labels#

querylabels→[LabelSummary!]!catalog_read

Every label in your catalog with how many releases it has, busiest first. Drafts and blocked deliveries are not counted.

Arguments

limitInt!Default: 200
Maximum number of labels to return. Clamped to 1–1000.

Returns

A list of LabelSummary objects.

Request

query {
  labels(limit: 3) {
    partyPk
    name
    releases
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  labels(limit: 3) {\n    partyPk\n    name\n    releases\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        labels(limit: 3) {
          partyPk
          name
          releases
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "labels": [
      { "partyPk": 90211, "name": "Lanternfish Records", "releases": 42 },
      { "partyPk": 90377, "name": "Coastline Sound", "releases": 17 },
      { "partyPk": 91002, "name": "Halcyon Audio", "releases": 5 }
    ]
  }
}

Create a party#

mutationcreateParty→DraftParty!catalog_write

Create an artist, label, producer or writer in your catalog, to credit with creditRelease or creditResource.

Parties are matched by DPID, not by name: passing a DPID that already exists returns the existing party, while creating two parties with the same name and no DPID makes two parties. Reuse the returned partyPk to credit the same party again.

Arguments

inputCreatePartyInput!required
The party to create.
Show child parameters
- nameString!required
  The party's name. Required and must not be blank.
- dpidString
  DDEX Party Identifier. If a party with this DPID already exists in your catalog, that party is returned instead.
- nameTypeString!Default: "FullName"
  The DDEX name type.

Returns

A DraftParty.

Request

mutation {
  createParty(input: { name: "Halfway Ghosts" }) {
    partyPk
    name
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  createParty(input: { name: \"Halfway Ghosts\" }) {\n    partyPk\n    name\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        createParty(input: { name: "Halfway Ghosts" }) {
          partyPk
          name
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "createParty": {
      "partyPk": 90450,
      "name": "Halfway Ghosts"
    }
  }
}

Credit a release#

mutationcreditRelease→Release!catalog_write

Credit a party on a release as a whole — the display artist, the label, anyone credited at album level. Crediting the same party in the same role twice has no further effect.

Arguments

releasePkInt!required
The release to credit.
inputCreditInput!required
Who, and in what role.
Show child parameters
- partyPkInt!required
  The party to credit, from createParty or an existing credit.
- roleString!required
  The DDEX role, e.g. MainArtist, Producer, Composer. Not Label — a label is set with labels on createRelease or updateRelease, and a Label credit is refused.
- roleKindString!Default: "DisplayArtistRole"
  The vocabulary role belongs to. DisplayArtistRole for release billing; ResourceContributorRole for track contributors.
- territoryString
  Leave unset unless the credit really applies to one territory only. Unset is not the same as Worldwide.
- sequenceInt
  Billing order.

Returns

The Release.

Request

mutation {
  creditRelease(
    releasePk: 48290
    input: { partyPk: 90450, role: "MainArtist" }
  ) {
    contributors { party { name } role }
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  creditRelease(\n    releasePk: 48290\n    input: { partyPk: 90450, role: \"MainArtist\" }\n  ) {\n    contributors { party { name } role }\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        creditRelease(
          releasePk: 48290
          input: { partyPk: 90450, role: "MainArtist" }
        ) {
          contributors { party { name } role }
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "creditRelease": {
      "contributors": [
        { "party": { "name": "Halfway Ghosts" }, "role": "MainArtist" }
      ]
    }
  }
}

Credit a resource#

mutationcreditResource→DraftResource!catalog_write

Credit a party on one track — a performer, producer, engineer or writer. Use roleKind: "ResourceContributorRole" for the people who worked on the recording.

Arguments

resourcePkInt!required
The resource to credit.
inputCreditInput!required
Who, and in what role.
Show child parameters
- partyPkInt!required
  The party to credit, from createParty or an existing credit.
- roleString!required
  The DDEX role, e.g. MainArtist, Producer, Composer. Not Label — a label is set with labels on createRelease or updateRelease, and a Label credit is refused.
- roleKindString!Default: "DisplayArtistRole"
  The vocabulary role belongs to. DisplayArtistRole for release billing; ResourceContributorRole for track contributors.
- territoryString
  Leave unset unless the credit really applies to one territory only. Unset is not the same as Worldwide.
- sequenceInt
  Billing order.

Returns

A DraftResource with the resource's current state.

Request

mutation {
  creditResource(
    resourcePk: 771340
    input: { partyPk: 90460, role: "Producer", roleKind: "ResourceContributorRole" }
  ) {
    resourcePk
    state
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  creditResource(\n    resourcePk: 771340\n    input: { partyPk: 90460, role: \"Producer\", roleKind: \"ResourceContributorRole\" }\n  ) {\n    resourcePk\n    state\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        creditResource(
          resourcePk: 771340
          input: { partyPk: 90460, role: "Producer", roleKind: "ResourceContributorRole" }
        ) {
          resourcePk
          state
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "creditResource": {
      "resourcePk": 771340,
      "state": "stored"
    }
  }
}

Remove a release credit#

mutationremoveReleaseCredit→Boolean!catalog_write

Withdraw one release-level credit. The party itself is not deleted — it may be credited elsewhere.

Arguments

releasePkInt!required
The release.
partyPkInt!required
The credited party.
roleString!required
The role to withdraw, e.g. MainArtist.
roleKindString!Default: "DisplayArtistRole"
The vocabulary the role belongs to.

Returns

true if a credit was removed.

Request

mutation {
  removeReleaseCredit(releasePk: 48290, partyPk: 90450, role: "FeaturedArtist")
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  removeReleaseCredit(releasePk: 48290, partyPk: 90450, role: \"FeaturedArtist\")\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        removeReleaseCredit(releasePk: 48290, partyPk: 90450, role: "FeaturedArtist")
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "removeReleaseCredit": true
  }
}

Remove a resource credit#

mutationremoveResourceCredit→Boolean!catalog_write

Withdraw one track-level credit. The party survives.

Arguments

resourcePkInt!required
The resource.
partyPkInt!required
The credited party.
roleString!required
The role to withdraw, e.g. Producer.
roleKindString!Default: "ResourceContributorRole"
The vocabulary the role belongs to.

Returns

true if a credit was removed.

Request

mutation {
  removeResourceCredit(resourcePk: 771340, partyPk: 90460, role: "Producer")
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  removeResourceCredit(resourcePk: 771340, partyPk: 90460, role: \"Producer\")\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        removeResourceCredit(resourcePk: 771340, partyPk: 90460, role: "Producer")
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "removeResourceCredit": true
  }
}