Songlinks

Use when the user names a songwriter or composer and wants to know who they are, which person a name belongs to, or every registration of that writer. Returns the persons the name could be: each with a person ID, the names and IPI name numbers they are registered under, how many works, and a person_url to cite. Pairs listed under possibly_the_same_person were held apart and are not merged; `why` says why. Candidates are this lookup's own grouping, made afresh for the name, and can differ from the stored person that get_songwriter and the person page describe: a candidate can include records with no IPI name number that the stored person lists apart, and two candidates can carry the same person_id when this lookup keeps apart records the stored person joined. Each record's person_id is the stored person it belongs to, or null; person_records is how many records that person holds, and records_not_in_this_answer how many of them this candidate does not, because they sit in another candidate or outside this lookup. For a person's registrations as they stand, call get_songwriter. A candidate's works counts every record in it, records held apart from the person included; the person's own count is get_songwriter's works.total. Registrations are under legal names: a writer known by a professional or stage name may not be found by it. If the writer you expect is not among the candidates, or song_match.match is none, try their legal name. truncated means more registrations matched than one answer groups: a fuller name narrows it. Give a song title they wrote, when known, to say which of several namesakes wrote it. A one-word name is not searched: ask for the full name.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "The songwriter's full name, as registered or as commonly written",
      "maxLength": 120,
      "minLength": 1,
      "title": "Name",
      "type": "string"
    },
    "song": {
      "anyOf": [
        {
          "maxLength": 200,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional: the title of a song they wrote",
      "title": "Song"
    }
  },
  "required": [
    "name"
  ],
  "title": "find_songwriterArguments"
}

Use when you have a Songlinks person ID (SLP-XXXX-XXXX-X), from find_songwriter or a person page, and the user wants that writer's details: the registrations grouped into the person, records listed apart as possibly the same person, and their first works. Each record says how it was joined: `main` marks the record the ID was issued on, and `rule` is the evidence: same_ipi (another of the person's records carries the same IPI name number), ipi (it carries the person's own number), model (judged the same writer from works, co-writers and publishers in common; `score` is how sure), corroborated (confirmed by an independent source) or verdict (decided by a person). At most 25 works are listed; works.total is the full count and the person page lists the rest. works.ordered_by is `recordings` when the list starts with the most-recorded works, and `coded` when it is in catalogue-code order: then it is a sample, not the writer's best-known songs.

{
  "type": "object",
  "properties": {
    "person_id": {
      "description": "A Songlinks person ID, SLP-XXXX-XXXX-X",
      "maxLength": 40,
      "minLength": 1,
      "title": "Person Id",
      "type": "string"
    }
  },
  "required": [
    "person_id"
  ],
  "title": "get_songwriterArguments"
}

Use when the user has an IPI name number (up to 11 digits, often written without its leading zeros) and wants to know which songwriter holds it. Returns the person or persons holding the number, each with a person ID and person_url; use get_songwriter for one person's details. `none` means no person here holds it: it may be a publisher's number, or one whose registrations have not been grouped.

{
  "type": "object",
  "properties": {
    "ipi_name_number": {
      "anyOf": [
        {
          "maxLength": 40,
          "minLength": 1,
          "type": "string"
        },
        {
          "minimum": 0,
          "type": "integer"
        }
      ],
      "description": "One IPI name number",
      "title": "Ipi Name Number"
    }
  },
  "required": [
    "ipi_name_number"
  ],
  "title": "songwriter_by_ipiArguments"
}

Use when the user has several IPI name numbers, such as the writers on a song, a catalogue or a registration file, and wants to know who each one is, or whether some of a writer's works sit under another spelling or number. Up to 50 numbers per call. For each: the person holding it, their registered names, works in total and on their main number, works_elsewhere (registered only under another spelling or number), and a person_url.

{
  "type": "object",
  "properties": {
    "ipi_name_numbers": {
      "description": "Up to 50 IPI name numbers",
      "items": {
        "anyOf": [
          {
            "maxLength": 40,
            "type": "string"
          },
          {
            "minimum": 0,
            "type": "integer"
          }
        ]
      },
      "maxItems": 100,
      "minItems": 1,
      "title": "Ipi Name Numbers",
      "type": "array"
    }
  },
  "required": [
    "ipi_name_numbers"
  ],
  "title": "check_writersArguments"
}