Data Submission Formats

From ISFDB
Revision as of 19:48, 8 May 2008 by Alvonruff (talk | contribs) (→‎AuthorUpdate: update)
Jump to navigation Jump to search

Introduction

The data submitted to the ISFDB must be a well-formed XML string. All submissions must contain the following:

  • An xml header utilizing version 1.0, and a recommended encoding of iso-8859-1.
  • The data must be enclosed within a set of IsfdbSubmission tags.
  • The data must contain a valid registered user within a set of Submitter tags.
  • The data must contain a subject heading within a set of Subject tags. This subject is displayed in the moderator queue, and is not integrated into the ISFDB data.

A stubbed out version of a generic submission looks like this: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <...Type...>
     <Submitter>Registered_User_Name</Submitter>
     <Subject>Subject Line That Will Appear in Moderator Queue</Subject>
     ...
  </...Type...>
</IsfdbSubmission>

Author Related Submissions

There are two data submission types necessary for the upkeep of the authors table: AuthorUpdate and AuthorMerge. AuthorUpdate handles changes made to the author-related tables; it has no side effects on other tables. AuthorMerge handles merging two authors together; it does have side effects on publication and title mapping tables, as one of the authors is replaced with the other.

AuthorMerge

The AuthorMerge submission specifies how two author records should be merged. The submission contains three required tags:

  • KeepId - Required tag. Specifies which author record will be retained.
  • DropId - Required tag. Specifies which author record will be dropped.
  • Range - Required tag. Specifies the range of changes:
    • TITLES - Only merges authors an the canonical_author table.
    • PUBS - Only merges authors in the pub_authors and aspub_author tables.
    • ALL - Applies changes to all author mapping tables.

The AuthorMerge submission also contains a number of optional tags. When a merging conflict occurs, these tags are used to specify which version of the data should be used:

  • Canonical - Use when a conflict exists between the canonical names.
  • Legalname - Use when a conflict exists between the legal names.
  • Birthplace - Use when a conflict exists between the birthplaces.
  • Birthdate - Use when a conflict exists between the birthdates
  • Deathdate - Use when a conflict exists between the deathdates.
  • Wikipedia - Use when a conflict exists between Wikipedia URLs.
  • Imdb - Use when a conflict exists between IMDB URLs.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <AuthorMerge>
     <Submitter>Rkihara</Submitter>
     <Subject>Elliott Dold/Elliott Dold</Subject>
     <KeepId>71501</KeepId>
     <DropId>84301</DropId>
     <Range>ALL</Range>
     <Legalname>84301</Legalname>
  </AuthorMerge>
</IsfdbSubmission>

AuthorUpdate

The AuthorUpdate submission updates author information for a single specific author. The submission contains one required tag

  • Record - Required tag. Specifies which author record to update.

The AuthorUpdate submission also contains a number of optional tags. These tags should be used whenever an update is made to a particular field. If a particular field is unchaged, it should not be included in the submission. If a field value needs to be deleted (for instance a webpage is decommissioned), the tag value should be empty. The following tags are supported:

  • Canonical - Should contain the author's canonical name.
  • Legalname - Should contain the author's legal name, in Lastname, Firstname format.
  • Lastname - Contains the author's last name. Used to set how the last names with multiple sections should be alphabetized, for instance "von Ruff" instead of "Ruff".
  • Birthplace - Should contain the author's birthplace, in Town,State,Country format.
  • Birthdate - Should contain the author's birthdate in YYYY-MM-DD format. If the month and day are unknown, YYYY-00-00 should be used.
  • Deathdate - Should contain the author's deathdate in YYYY-MM-DD format. If the month and day are unknown, YYYY-00-00 should be used. If the author is known to be dead, but the deathdate is unknown 0000-00-00 is acceptable.
  • Emails - Should contain a list of the child tag Email, which should contain the author's email addresses. There should be a separate Email tag (enclosed within a single Emails tag) for each email address.
  • Webpages - Should contain a list of the child tag Webpage, which should contain the author's website URL. There should be a separate Webpage tag (enclosed within a single Webpages tag) for each website.
  • Wikipedia - Should contain the URL to the author's Wikipedia article.
  • Imdb - Should contain the URL to the author's IMDB filmography.
  • Image - Should contain the URL to an author picture.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <AuthorUpdate>
    <Record>347</Record>
    <Subject>David Duncan</Subject>
    <Submitter>ErnestoVeg</Submitter>
    <Birthdate>1913-02-17</Birthdate>
    <Deathdate>1999-12-26</Deathdate>
  </AuthorUpdate>
</IsfdbSubmission>

Publication Related Submissions

PubUpdate

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <PubUpdate>
    <Record>56773</Record>
    <Submitter>Davecat</Submitter>
    <Subject>Analog Science Fact -> Science Fiction, September 1962</Subject>
    <Note>Vol. LXX, No. 1.
    "The Professional Approach" is listed in table of contents as a short story.
    The credit at the head of the editorial is "John V. Campbell", surely a typo.
    "The First Science" is listed simply as "Article"; possibly it should be in the Science Fact series.
    Arguably, the illustration on pp. 76-77 is two separate illustrations.
    "Statistics Are Wonderful" is not in table of contents.
    I believe that the art credit for "Sorcerer’s Apprentice" is "Brev", but it might be "Brey".
    "Brass Tacks" includes a letter by G. Harry Stine.
    The reviews listed as being on pp. 152-153 are scattered through Miller’s initial essay, titled  "Dealer’s Choice".
    The review of The Lani People incorrectly gives the author as F. F. Bone.</Note>
    <Content>
      <ContentReview>
        <cTitle>The Sixth Galaxy Reader</cTitle>
        <cBookAuthors>H. L. Gold</cBookAuthors>
        <cReviewers>P. Schuyler Miller</cReviewers>
        <cDate>1962-09-00</cDate>
        <cPage>152</cPage>
      </ContentReview>
    </Content>
  </PubUpdate>
</IsfdbSubmission>

PubDelete

The PubDelete submission deletes the specified publication record. The submission contains one required tag:

  • Record - Required tag. Specifies which author record to delete.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <PubDelete>
    <Record>71486</Record>
  </PubDelete>
</IsfdbSubmission>

NewPub

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <NewPub>
  <Submitter>Ahasuerus</Submitter>
  <Subject>Sweet and Deadly</Subject>
  <Parent>185660</Parent>
  <Title>Sweet and Deadly</Title>
  <Year>1981-00-00</Year>
  <Publisher>Houghton Mifflin</Publisher>
  <Pages>179</Pages>
  <Binding>hc</Binding>
  <PubType>NOVEL</PubType>
  <Isbn>0395305322</Isbn>
  <Price>$8.95</Price>
  <Note>Data from OCLC record 6915310.</Note>
  <Authors>
    <Author>Charlaine Harris</Author>
  </Authors>
  <Content>
  </Content>
  </NewPub>
</IsfdbSubmission>

Title Related Submissions

TitleUpdate

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
  <IsfdbSubmission>
    <TitleUpdate>
    <Record>11114</Record>
    <Submitter>DESiegel60</Submitter>
    <Subject>Breed to Come</Subject>
    <Year>1972-00-00</Year>
  </TitleUpdate>
</IsfdbSubmission>

TitleMerge

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <TitleMerge>
    <KeepId>7287</KeepId>
    <DropId>170262</DropId>
    <Title>7287</Title>
    <Year>7287</Year>
    <Series>7287</Series>
    <Seriesnum>7287</Seriesnum>
  </TitleMerge>
</IsfdbSubmission>

TitleDelete

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <TitleDelete>
    <Subject>The Petrified Planet</Subject>
    <Submitter>Ahasuerus</Submitter>
    <Record>825280</Record>
    <Reason>Dup title.</Reason>
  </TitleDelete>
</IsfdbSubmission>

TitleUnmerge

Retrieved from "https://isfdb.org/wiki/index.php?title=Data_Submission_Formats&oldid=119140"