Filling Out the Reference List Classes

From The SBN Wiki
Revision as of 03:37, 24 January 2013 by Raugh (talk | contribs) (: Replace "Questions" links)
Jump to navigation Jump to search

The <Reference_List> class provides a list of internal (i.e., to other PDS4 products) and external citations relevant to the product. Use this class for references and associations you want to make that are not already included elsewhere in the product label.

The internal references in this class provide the primary method for making associations like:

  • Raw data to calibrated data
  • Calibrated data to the calibration observation(s) used
  • Data to documentation on calibration or observing conditions
  • and so on.

The external references provide a way to direct users to books or articles related to the product, or to documents not included in the archive because of copyright issues.

Note: It is almost never appropriate to cite a web site as a reference in the archive. The PDS archives are designed for generations. Our mandate is to keep the data available and usable for 50-100 years, or more. You should not refer users to any external reference that is not reasonably likely to have a similar lifespan. Very few websites meet that criterion.
Fortunately, it is generally possible to get permission from the website author/manager to take a snapshot of the relevant pages, which can then be labelled as a PDS Document product, included in the archive with the data, and cited as an internal reference.

The <Reference_List> class is itself optional. When it is included, all internal references (if any) are listed first; external references (if any) are listed second. You may include as many of each type of reference as you like.

For additional explanation, see the PDS4 Standard Reference, or contact your PDS node consultant.

Following are the attributes and subclasses you'll find in <Reference_List>, in label order.

Note that in the PDS4 master schema, all classes have capitalized names; attributes never do.

<Internal_Reference>

OPTIONAL

This class provides a direct reference to the logical identifier of another product somewhere in the PDS4 registry. A specific version can be referenced, if appropriate.

The <Internal_Reference> format is the same wherever it appears.

<lid_reference> or <lidvid_reference>

REQUIRED

Either a logical ID (LID) reference or a LID reference with an additional version ID (VID) must be provided (but not both). If <lid_reference> is used, the value must match the <logical_identifier> value of some other PDS4 product in the registry (this will be checked when the product is officially registered). Similarly, when a <lidvid_reference> is used, the value has the format logical_identifier::version_identifier, and there must be a product with the given <logical_identifier> and <version_identifier> values.

<reference_type>

REQUIRED

This must be one of the standard values defined for the context in which the Internal_Reference appears. We keep a list of these on the Standard Values Quick Reference page. Note that there are several different lists for <reference_type>, depending on the surrounding context. Be careful to select from the list corresponding to the part of the label structure you're working on.

These standard value lists are likely to grow - if you need a new value, let your PDS contact person know.

<comment>

OPTIONAL

This is a place to put a bit of text as needed to explain why you're referencing the product mentioned above. Formatting is preserved.

<External_Reference>

OPTIONAL

This class provides a way to cite sources external to the PDS4 registry.

<doi>

OPTIONAL

If you're citing a publication that has a Digital Object Identifier (DOI), the DOI can be called out separately here. Include only the actual DOI - not the "doi:" or "DOI:" tag frequently included in citations.

<reference_text>

REQUIRED

This is the full text of the citation. For SBN data sets, we'd like to see these in the format used for the Astrophysics Data System citations - that is, each author is listed as surname, initials, with semi-colons between authors. You can repeat the DOI here, if you like, using the doi: tag to identify it in-line.

Space is not preserved in this text.

<description>

OPTIONAL

This is a free-text field (space is preserved) for adding any additional details or description you might care to include about the reference being cited. Why you are citing this reference would be an excellent thing to put here.