Data Submission Formats

From ISFDB
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.

  • XML: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.
  • XML:AuthorUpdate - handles changes made to the author-related tables; it has no side effects on other tables.

Publication Related Submissions

PubUpdate

The PubUpdate submission updates publication information for a single specific publication. The submission contains one required tag:

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

The PubUpdate 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, the tag should be included, but the value should be empty. The following section describes the tags are supported in the metadata section. You should refer to Help:Screen:EditPub for more detailed information on data entry. The bold text in the description refers to specific labels found in the Help article:

  • Title - The Title of the publication.
  • Authors - The Author list associated with the publication. This XML tag will enclose:
    • Author - There should be one Author entry for each individual who wrote or edited the publication.
  • Artists - The Artist list associated with the publication. This XML tag will enclose:
    • Artist - There should be one Artist entry for each individual who wrote or edited the publication.
  • Tag - Unique ASCII identifier for the publication.
  • Year - The Year of publication.
  • Pages - The number of Pages in the publication.
  • Binding - The Pub Format of the publication.
  • PubType - The Pub Type type of the publication.
  • Isbn - The ISBN / Catalog # of the publication.
  • Price - The Price of the publication.
  • Image - The Image URL associated with the publication cover art.
  • Note - A Note specific to this publication.
  • Publisher - The Publisher of the publication.
  • Content - Some amount of content may be associated with the publication. Only those titles undergoing change should be included in this section. If no titles are modified, the Content section must be present, although it will be empty. Any number of the following content type entries are supported:
    • ContentTitle - This is for normal content, such as short stories or essays.
    • ContentReview - This is a specialized format for reviews, taking into account the author writing the review, and the author who wrote the work being reviewed.
    • ContentInterview - This is a specialized format for interviews, taking into account the author that conducted the interview, and the author who was interviewed.

ContentTitle

Refer to Help:Screen:EditPub#General_contents for detailed data-entry help:

  • Record - The record number of the title. If missing the title is considered new.
  • cTitle - The name of the title.
  • cAuthors - The author(s) of the title. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the title.
  • cPage - The page the title appears on.
  • cType - The Entry Type of the title.
  • cLength - The Length of the title.

ContentReview

Refer to Help:Screen:EditPub#Reviews for detailed data-entry help:

  • Record - The record number of the title. If missing the review is considered new.
  • cTitle - The name of the title.
  • cBookAuthors - The author(s) of the book being reviewed. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cReviewers - The author(s) writing the review. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the review.
  • cPage - The page the review appears on.

ContentInterview

Refer to Help:Screen:EditPub#Interviews for detailed data-entry help:

  • Record - The record number of the title. If missing the interview is considered new.
  • cTitle - The name of the title.
  • cInterviewee - The author(s) conducting the interview. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cInterviewer - The author(s) being interviewed. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the interview.
  • cPage - The page the interview appears on.

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.</Note>
    <Content>
      <ContentTitle>
        <Record>772165</Record>
        <cTitle>Hugos and Others</cTitle>
        <cAuthors>The Editor</cAuthors>
      </ContentTitle>
      <ContentTitle>
        <Record>54317</Record>
        <cLength>ss</cLength>
      </ContentTitle>
      <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>
      <ContentInterview>
        <cTitle>Dan Simmons Interview</cTitle>
        <cInterviewees>Dan Simmons</cInterviewees>
        <cInterviewers>Bob Morrish</cInterviewers>
        <cDate>1990-00-00</cDate>
      </ContentInterview>
    </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.

Optional tag:

  • Reason - The reason the publication is being deleted.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <PubDelete>
    <Subject>Mutants</Subject>
    <Submitter>Mhhutchins</Submitter>
    <Record>179041</Record>
    <Reason>No reason given.</Reason>
  </PubDelete>
</IsfdbSubmission>

NewPub

The NewPub submission generates new publication information for a single specific publication. The submission contains contains a number of optional tags. These tags should be used whenever the relevant data is available for a particular field. The following section describes the tags are supported in the metadata section. You should refer to Help:Screen:NewPub for more detailed information on data entry. The bold text in the description refers to specific labels found in the Help article:

  • Title - The Title of the publication.
  • Authors - The Author list associated with the publication. This XML tag will enclose:
    • Author - There should be one Author entry for each individual who wrote or edited the publication.
  • Artists - The Artist list associated with the publication. This XML tag will enclose:
    • Artist - There should be one Artist entry for each individual who wrote or edited the publication.
  • Tag - Unique ASCII identifier for the publication. Used for magazines.
  • Year - The Year of publication.
  • Pages - The number of Pages in the publication.
  • Binding - The Pub Format of the publication.
  • PubType - The Pub Type type of the publication.
  • Isbn - The ISBN / Catalog # of the publication.
  • Price - The Price of the publication.
  • Image - The Image URL associated with the publication cover art.
  • Note - A Note specific to this publication.
  • Publisher - The Publisher of the publication.
  • Parent - Used to automerge the publication. The parent id is record number of the parent title.
  • Content - For non-novels, some amount of content may be associated with the publication. Only those titles undergoing change should be included in this section. If no titles are modified, the Content section must be present, although it will be empty. Any number of the following content type entries are supported:
    • ContentTitle - This is for normal content, such as short stories or essays.
    • ContentReview - This is a specialized format for reviews, taking into account the author writing the review, and the author who wrote the work being reviewed.
    • ContentInterview - This is a specialized format for interviews, taking into account the author that conducted the interview, and the author who was interviewed.

ContentTitle

Refer to Help:Screen:NewPub#General_contents for detailed data-entry help:

  • cTitle - The name of the title.
  • cAuthors - The author(s) of the title. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the title.
  • cPage - The page the title appears on.
  • cType - The Entry Type of the title.
  • cLength - The Length of the title.

ContentReview

Refer to Help:Screen:NewPub#Reviews for detailed data-entry help:

  • cTitle - The name of the title.
  • cBookAuthors - The author(s) of the book being reviewed. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cReviewers - The author(s) writing the review. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the review.
  • cPage - The page the review appears on.

ContentInterview

Refer to Help:Screen:NewPub#Interviews for detailed data-entry help:

  • cTitle - The name of the title.
  • cInterviewee - The author(s) conducting the interview. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cInterviewer - The author(s) being interviewed. Note that multiple authors are separated with a +; they are not enclosed in separate XML tags.
  • cDate - The copyright date of the interview.
  • cPage - The page the interview appears on.

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>


TitleRemove

The TitleRemove submission removes one or more titles from a publication. The submission contains two required tags:

  • Record - Specifies which publication record to update.
  • TitleRecord - Specifies which title record to remove. Multiple tags may be submitted to remove multiple titles from the publication.

Example: 

 <?xml version="1.0" encoding="iso-8859-1" ?>
 <IsfdbSubmission>
   <TitleRemove>
     <Subject>Year’s Best Fantasy 4</Subject>
     <Submitter>CoachPaul</Submitter>
     <Record>117691</Record>
     <TitleRecord>309491</TitleRecord>
   </TitleRemove>
 </IsfdbSubmission>

Title Related Submissions

TitleUpdate

The TitleUpdate submission updates title information for a single specific title. The submission contains one required tag:

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

The TitleUpdate 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 unchanged, it should not be included in the submission. If a field value needs to be deleted, the tag should be included, but the value should be empty. The following section describes the tags are supported in the metadata section. You should refer to Help:Screen:EditTitle for more detailed information on data entry. The bold text in the description refers to specific labels found in the Help article:

  • Title - The Title of the title.
  • Authors - The Author list associated with the title. This XML tag will enclose:
    • Author - There should be one Author entry for each individual who wrote or edited the title.
  • BookAuthors - The Author list associated with the authors who's work appeared in this review. This XML tag will enclose:
    • BookAuthor - There should be one Author entry for each individual who wrote the title being reviewed.
  • Interviewees - The Author list associated with who was interviewed. This XML tag will enclose:
    • Interviewee - There should be one Author entry for each individual who was interviewed.
  • Year - The Date of publication.
  • Series - The Series Name this title is associated with.
  • Seriesnum - The Series Number of this title.
  • Storylen - The Length of this title.
  • Wikipedia - A URL to a Wikipedia Entry on this title.
  • TitleType - The Entry Type of this title.
  • Synopsis - The Synopsis of this title.
  • Note - A Note associated with this title.

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

The TitleMerge submission merges 2 or more titles into a single title. The submission contains one required tag:

  • KeepId - Required tag. Specifies which title record to retain. All others will be discarded after the merge.

The TitleMerge submission also contains a number of optional tags. These tags should be used whenever a particular field differs between the merged titles. Each used tag refers to a title record number. When the submission is integrated, the value associated with the named record will be retained. For instance, say there are 3 titles being merged which have copyright years of 1952, 1953, and 1980. A Year merge tag is generated which selects the record associated with the year 1952. When the submission is integrated, if the retained title record has a year value other than 1952, then that value will be copied into the retained record. The tags contain only record numbers; they do not contain data values.

The following section describes the tags are supported in the metadata section. You should refer to Editing:Merging_Titles for more detailed information on data entry:

  • Title - Record number with the desired title.
  • Author - Record number with the desired authors.
  • Year - Record number with the desired copyright year.
  • TitleType - Record number with the desired entry type.
  • Series - Record number with the desired series name.
  • Seriesnum - Record number with the desired series number.
  • Storylen - Record number with the desired length.
  • Synopsis - Record number with the desired synopsis.
  • Wikipedia - Record number with the desired wikipedia URL.
  • Note - Record number with the desired note.
  • Parent - Record number with the desired parent (for variant titles).

Example: 

<?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

The TitleDelete submission deletes the indicated title. The must be no publications referring to this title. The submission contains two required tags:

  • Record - Required tag. Record number of the title.
  • Reason - The reason for deletion. This is a plain text field.

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

The TitleUnmerge submission is used to split off titles that were previously merged. The indicated publications will point to brand new titles. These titles will have the same title name and year as the publication records they were created from. The submission contains two required tags:

  • Record - Record number of the parent title.
  • PubRecord - Record number of the target publication. There may be more than one publication targeted per submission.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <TitleUnmerge>
    <Submitter>Alvonruff</Submitter>
    <Subject>Galactic North</Subject>
    <Record>198738</Record>
    <PubRecord>104411</PubRecord>
    <PubRecord>89771</PubRecord>
</TitleUnmerge>
</IsfdbSubmission>

MakeVariant

This submission is used to make current title a variant title. It can either link to an existing parent title, or it can specify that a parent title be created.

Example where parent exists: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <MakeVariant>
    <Submitter>CoachPaul</Submitter>
    <Subject>Luella Miller</Subject>
    <Record>883909</Record>
    <Parent>99468</Parent>
  </MakeVariant>
</IsfdbSubmission>

Example where parent is created: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <MakeVariant>
    <Record>884039</Record>
    <Submitter>Rkihara</Submitter>
    <Subject>Buying Time: A Jaunt in Time and Space</Subject>
    <Title>Buying Time: A Jaunt in Time and Space</Title>
    <Year>2001-00-00</Year>
    <TitleType>NOVEL</TitleType>
    <Authors>
      <Author>Alan Glasser</Author>
    </Authors>
  </MakeVariant>
</IsfdbSubmission>

VariantTitle

This submission is used to add a variant title to the current title. This is useful if you know from a secondary bibliography that a variant title exists, but no publication has every been entered under that title as yet. Usage of this submission type is fairly rare.

Example: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
  <VariantTitle>
    <Submitter>Ahasuerus</Submitter>
    <Subject>Nad Bezdnoj</Subject>
    <Parent>877998</Parent>
    <Title>Nad Chernoj Bezdnoj</Title>
    <Year>1927-00-00</Year>
    <Storylen>ss</Storylen>
    <TitleType>SHORTFICTION</TitleType>
    <Note>Originally published as "Nad Chernoj Bezdnoj", book publication as "Nad Bezdnoj".</Note>
    <Authors>
      <Author>Alexander Beliaev</Author>
    </Authors>
  </VariantTitle>
</IsfdbSubmission>
Retrieved from "https://isfdb.org/wiki/index.php?title=Data_Submission_Formats&oldid=119948"