Difference between revisions of "Data Submission Formats"

From ISFDB
Jump to navigation Jump to search
 
(27 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
 +
Data is submitted to the ISFDB either from the online editing tools, or by the [[Web API]]. Accepted submissions are placed in the [[Database_Schema#submissions|submissions]] table in the MySQL database.
 
The data submitted to the ISFDB must be a well-formed XML string. All submissions must contain the following:
 
The data submitted to the ISFDB must be a well-formed XML string. All submissions must contain the following:
  
Line 10: Line 11:
 
A stubbed out version of a generic submission looks like this:
 
A stubbed out version of a generic submission looks like this:
  
 +
<source lang="xml">
 
  <?xml version="1.0" encoding="iso-8859-1" ?>
 
  <?xml version="1.0" encoding="iso-8859-1" ?>
 
  <IsfdbSubmission>
 
  <IsfdbSubmission>
Line 18: Line 20:
 
   </...Type...>
 
   </...Type...>
 
  </IsfdbSubmission>
 
  </IsfdbSubmission>
 +
</source>
  
 
==Author Related Submissions==
 
==Author Related Submissions==
  
−
There are two data submission types necessary for the upkeep of the authors table: '''AuthorUpdate''' and '''AuthorMerge'''.
+
There are three data submission types necessary for the upkeep of the authors table:
  
−
* [[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:AuthorMerge]] - Merges two author records together.
−
* [[XML:AuthorUpdate]] - handles changes made to the author-related tables; it has no side effects on other tables.
+
* [[XML:AuthorUpdate]] - Updates an author record.
 +
* [[XML:MakePseudonym]] - Makes an author record a alternate name.
 +
 
 +
Note that there are no submission types to create or delete author entries. Author entries are created on demand when a title or publication requires them. Likewise author entries are deleted when no other records refer to them.
  
 
==Publication Related Submissions==
 
==Publication Related Submissions==
  
−
* [[XML:PubUpdate]] - Updates a publication record.
+
There are four data submission types necessary for the upkeep of the pubs table:
 +
 
 +
* [[XML:NewPub]] - Adds a new publication record.
 
* [[XML:PubDelete]] - Deletes a publication record.
 
* [[XML:PubDelete]] - Deletes a publication record.
−
* [[XML:NewPub]] - Adds a new publication record.
+
* [[XML:PubUpdate]] - Modifies a publication record.
 
* [[XML:TitleRemove]] - Removes one or more titles from a publication record.
 
* [[XML:TitleRemove]] - Removes one or more titles from a publication record.
  
 
==Title Related Submissions==
 
==Title Related Submissions==
  
−
===TitleUpdate===
+
There are six data submission types necessary for the upkeep of the titles table:
  
−
The TitleUpdate submission updates title information for a single specific title. The submission contains one required tag:
+
* [[XML:LinkReview]] - Links a review record to the reviewed title.
 +
* [[XML:MakeVariant]] - Makes the current title a variant title.
 +
* [[XML:TitleDelete]] - Deletes a title record.
 +
* [[XML:TitleMerge]] - Merges two or more title records.
 +
* [[XML:TitleUnmerge]] - Unmerges one or more title records.
 +
* [[XML:TitleUpdate]] - Modifies a title record.
 +
* [[XML:VariantTitle]] - Adds a variant title to the current title.
  
−
* '''Record''' - Required tag. Specifies which title record to update.
+
==Series Related Submissions==
  
−
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:
+
There is one series-related data submission type:
  
−
* '''Title''' - The '''Title''' of the title.
+
* [[XML:SeriesUpdate]] - Updates a series record.
−
* '''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:
+
Note that there are no submission types to create or delete series entries. Series entries are created on demand when a title requires them. There is a submission type to delete an empty series, but it shouldn't be used via the Web API.
  
−
<?xml version="1.0" encoding="iso-8859-1" ?>
+
==Awards Related Submissions==
−
  <IsfdbSubmission>
 
−
    <TitleUpdate>
 
−
    <Record>11114</Record>
 
−
    <Submitter>DESiegel60</Submitter>
 
−
    <Subject>Breed to Come</Subject>
 
−
    <Year>1972-00-00</Year>
 
−
  </TitleUpdate>
 
−
</IsfdbSubmission>
 
  
−
===TitleMerge===
+
There are three data submission types necessary for the upkeep of the awards table:
  
−
The TitleMerge submission merges 2 or more titles into a single title. The submission contains one required tag:
+
* [[XML:NewAward]] - Creates a new award record.
 +
* [[XML:AwardDelete]] - Deletes an award record.
 +
* [[XML:AwardUpdate]] - Updates an award record.
  
−
* '''KeepId''' - Required tag. Specifies which title record to retain. All others will be discarded after the merge.
+
==Publisher Related Submissions==
  
−
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.
+
There are two data submission types necessary for the upkeep of the publishers table:
  
−
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:
+
* [[XML:PublisherUpdate]] - Updates a publisher record.
 +
* [[XML:PublisherMerge]] - Merges two or more publisher records.
  
−
* '''Title''' - Record number with the desired title.
+
Note that there are no submission types to create or delete publisher entries. Publisher entries are created on demand when a publication requires them. Likewise publisher entries are deleted when no other publications refer to them.
−
* '''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:
+
==See Also==
 +
* [[Web API]] -- Page that describes the API within which these formats may be used
 +
* [[Help:Screen:EditPub]] -- detailed help on the various publication-level fields and how they are used.
 +
* [[Help:Screen:EditTitle]] -- detailed help on the various title-level fields and how they are used.
  
−
<?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:
+
[[Category:Data Submission Formats]]
−
 
 
−
* '''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>
 

Latest revision as of 10:21, 27 June 2019

Introduction

Data is submitted to the ISFDB either from the online editing tools, or by the Web API. Accepted submissions are placed in the submissions table in the MySQL database. 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 three data submission types necessary for the upkeep of the authors table:

Note that there are no submission types to create or delete author entries. Author entries are created on demand when a title or publication requires them. Likewise author entries are deleted when no other records refer to them.

Publication Related Submissions

There are four data submission types necessary for the upkeep of the pubs table:

Title Related Submissions

There are six data submission types necessary for the upkeep of the titles table:

Series Related Submissions

There is one series-related data submission type:

Note that there are no submission types to create or delete series entries. Series entries are created on demand when a title requires them. There is a submission type to delete an empty series, but it shouldn't be used via the Web API.

Awards Related Submissions

There are three data submission types necessary for the upkeep of the awards table:

Publisher Related Submissions

There are two data submission types necessary for the upkeep of the publishers table:

Note that there are no submission types to create or delete publisher entries. Publisher entries are created on demand when a publication requires them. Likewise publisher entries are deleted when no other publications refer to them.

See Also

  • Web API -- Page that describes the API within which these formats may be used
  • Help:Screen:EditPub -- detailed help on the various publication-level fields and how they are used.
  • Help:Screen:EditTitle -- detailed help on the various title-level fields and how they are used.
Retrieved from "https://isfdb.org/wiki/index.php?title=Data_Submission_Formats&oldid=552161"