This site may be down for up to an hour for network maintenance during the period
21 January 2022 22:30 UTC - 22 January 2022 00:30 UTC.

Difference between revisions of "Filling Out the Reference List Classes"

From The SBN Wiki
Jump to navigation Jump to search
(Creation - Safety Save)
 
(: Update for IM 1.14.0.0)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
The ''''<Reference_List>''''' class provides a list of internal (i.e., to other PDS4 products) and external citations relevant to the product.  The internal references in this class provide the primary method for making associations like:
+
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
 
* Raw data to calibrated data
Line 5: Line 7:
 
* Data to documentation on calibration or observing conditions
 
* Data to documentation on calibration or observing conditions
 
* and so on.
 
* 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.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
:'''''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.
 
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.
+
For additional explanation, see the PDS4 ''Standards Reference'', or contact your PDS node consultant.
  
 
Following are the attributes and subclasses you'll find in ''<Reference_List>'', in label order.
 
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.
+
''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 ''&lt;Internal_Reference&gt;'' 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 ''&lt;lid_reference&gt;'' is used, the value must match the ''&lt;logical_identifier&gt;'' value of some other PDS4 product in the registry (this will be checked when the product is officially registered).  Similarly, when a ''&lt;lidvid_reference&gt;'' is used, the value has the format '''''logical_identifier::version_identifier''''', and there must be a product with the given ''&lt;logical_identifier&gt;'' '''and''' ''&lt;version_identifier&gt;'' 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#.3Creference_type.3E|Standard Values Quick Reference]] page.  Note that there are several different lists for ''&lt;reference_type&gt;'', depending on the surrounding context.  Be careful to select from the list corresponding to the part of the label structure you're working on.  If you don't find the context you're looking for here, then you should check the complete listings in ''PDS4 Data Dictionary'' to find the answer.  If you still can't find a valid value for your context, contact PDS.
 +
 
 +
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 when it's not immediately obvious from the ''reference_type''.  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. 
 +
 
 +
 
 +
== <Source_Product_Internal> ==
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
| '''Note:''' ''This class only makes sense in ''Product_Observational'' labels.  This is not currently constrained or validated, though.
 +
|}
 +
 
 +
This class is used to link to one or more source products that are in the PDS4 registry system.  This class is specifically used to link derived data to a list of progenitor products - so, for example, all the calibrated images that contributed to a mosaic.  Use one instance of this class for each type of ''relationship'' you need to document.  In other words, all the LIDVIDs listed should have the relationship indicated by the ''&lt;reference_type&gt;''.  If you need a different ''&lt;reference_type&gt;'' for one or more source products, use an additional ''Source_Product_Internal'' class.
 +
 
 +
=== <lidvid_reference> ===
 +
 
 +
''REQUIRED''
 +
 
 +
You ''must'' reference the source product(s) by both logical identifier (LID) and version (VID) - or LIDVID.  Repeat this attribute for each source product you want to reference with the associated ''reference_type'', following.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
| '''''Note:''''' It is not possible at present for the PDS4 ''Validate Tool'' to validate if any referenced product is registered.  Please type carefully.
 +
|}
 +
 
 +
=== <reference_type> ===
 +
 
 +
''REQUIRED''
 +
 
 +
This attribute must have one of the following values:
 +
 
 +
:* '''data_to_calibrated_source_product'''
 +
:* '''data_to_derived_source_product'''
 +
:* '''data_to_partially_processed_source_product'''
 +
:* '''data_to_raw_source_product'''
 +
:* '''data_to_telemetry_source_product'''
 +
 
 +
This attribute ''may not'' be repeated. Add another ''&lt;Source_Product_Internal&gt;'' class to reference a different type of source product.
 +
 
 +
=== <comment> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
This is a free-text (ASCII only) field for any additional information that might be useful to include.
 +
 
 +
== <Source_Product_External> ==
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
| '''Note:''' ''This class only makes sense in ''Product_Observational'' labels.  This is not currently constrained or validated, though.
 +
|}
 +
 
 +
This class is used to reference progenitor products that come from a common external archive or facility (so that the product identifications are of the same type).  You can repeat this class if you have source products from different sources, or if source products from the same source have different ''reference_type'' values.
 +
 
 +
=== <external_source_product_identifier> ===
 +
 
 +
''REQUIRED''
 +
 
 +
This attribute contains the identifier used in the source system of the product being referenced - a catalog number, for example.  It should be given in the syntax appropriate to that external system, so that a user could use the value here to search the database of the source facility.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
| '''''Note:''''' The description of this element contains a reference to a non-existent section in a document.  If you need this class, check with your PDS consultant for the correct format for your external product reference strings.
 +
|}
 +
 
 +
This attribute may be repeated for each external product you wish to reference.  Note, however, the issue related to ''&lt;doi&gt;'', below.
 +
 
 +
=== <reference_type> ===
 +
 
 +
''REQUIRED''
 +
 
 +
This must have one of the following values:
 +
 
 +
:* '''data_to_calibrated_source_product'''
 +
:* '''data_to_derived_source_product'''
 +
:* '''data_to_partially_processed_source_product'''
 +
:* '''data_to_raw_source_product'''
 +
:* '''data_to_telemetry_source_product'''
 +
 
 +
=== <doi> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
'''Note:''' ''at least one of ''&lt;doi&gt;'' and ''&lt;curating_facility&gt;'' '''must''' be supplied''
 +
 
 +
This attribute should be the DOI of the source products.  If more than one ''external_source_product_identifier'' is supplied, the identifiers must '''''all''''' be associated with this DOI.  If that is not the case, use a separate ''&lt;Source_Product_External&gt;'' for each unique DOI. If there are more product identifiers associated with the DOI than are listed in this class, then it would be appropriate to include a ''&lt;description&gt;'' that indicates how the specific, listed products were selected.
 +
 
 +
This DOI is being preserved as an archive attribute, and thus should be formatted as just the DOI, without the ''http://doi.org'' prefix.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
| The DOI-to-product relationship is important to get right.  There is no way for PDS to validate this, so please be conscientious when listing DOIs and associated identifiers from other archives and facilities.
 +
|}
 +
 
 +
=== <curating_facility> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
'''Note:''' ''at least one of ''&lt;doi&gt;'' and ''&lt;curating_facility&gt;'' '''must''' be supplied''
 +
 
 +
The full, formal name of the external (to PDS) agency or facility that maintains and distributes the product(s) referenced should be included here, if at all possible. This is critical for external sources not associated with a DOI.
 +
 
 +
=== <description> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
Use this attribute to provide any additional explanation or information that would be needed or useful to a user who is attempting to locate the source being referenced.  UTF-8 characters beyond the ASCII character set may be used (letters with diacritical marks, for example).

Latest revision as of 17:45, 31 July 2020

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 Standards 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. If you don't find the context you're looking for here, then you should check the complete listings in PDS4 Data Dictionary to find the answer. If you still can't find a valid value for your context, contact PDS.

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 when it's not immediately obvious from the reference_type. 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.


<Source_Product_Internal>

OPTIONAL

Note: This class only makes sense in Product_Observational labels. This is not currently constrained or validated, though.

This class is used to link to one or more source products that are in the PDS4 registry system. This class is specifically used to link derived data to a list of progenitor products - so, for example, all the calibrated images that contributed to a mosaic. Use one instance of this class for each type of relationship you need to document. In other words, all the LIDVIDs listed should have the relationship indicated by the <reference_type>. If you need a different <reference_type> for one or more source products, use an additional Source_Product_Internal class.

<lidvid_reference>

REQUIRED

You must reference the source product(s) by both logical identifier (LID) and version (VID) - or LIDVID. Repeat this attribute for each source product you want to reference with the associated reference_type, following.

Note: It is not possible at present for the PDS4 Validate Tool to validate if any referenced product is registered. Please type carefully.

<reference_type>

REQUIRED

This attribute must have one of the following values:

  • data_to_calibrated_source_product
  • data_to_derived_source_product
  • data_to_partially_processed_source_product
  • data_to_raw_source_product
  • data_to_telemetry_source_product

This attribute may not be repeated. Add another <Source_Product_Internal> class to reference a different type of source product.

<comment>

OPTIONAL

This is a free-text (ASCII only) field for any additional information that might be useful to include.

<Source_Product_External>

OPTIONAL

Note: This class only makes sense in Product_Observational labels. This is not currently constrained or validated, though.

This class is used to reference progenitor products that come from a common external archive or facility (so that the product identifications are of the same type). You can repeat this class if you have source products from different sources, or if source products from the same source have different reference_type values.

<external_source_product_identifier>

REQUIRED

This attribute contains the identifier used in the source system of the product being referenced - a catalog number, for example. It should be given in the syntax appropriate to that external system, so that a user could use the value here to search the database of the source facility.

Note: The description of this element contains a reference to a non-existent section in a document. If you need this class, check with your PDS consultant for the correct format for your external product reference strings.

This attribute may be repeated for each external product you wish to reference. Note, however, the issue related to <doi>, below.

<reference_type>

REQUIRED

This must have one of the following values:

  • data_to_calibrated_source_product
  • data_to_derived_source_product
  • data_to_partially_processed_source_product
  • data_to_raw_source_product
  • data_to_telemetry_source_product

<doi>

OPTIONAL

Note: at least one of <doi> and <curating_facility> must be supplied

This attribute should be the DOI of the source products. If more than one external_source_product_identifier is supplied, the identifiers must all be associated with this DOI. If that is not the case, use a separate <Source_Product_External> for each unique DOI. If there are more product identifiers associated with the DOI than are listed in this class, then it would be appropriate to include a <description> that indicates how the specific, listed products were selected.

This DOI is being preserved as an archive attribute, and thus should be formatted as just the DOI, without the http://doi.org prefix.

The DOI-to-product relationship is important to get right. There is no way for PDS to validate this, so please be conscientious when listing DOIs and associated identifiers from other archives and facilities.

<curating_facility>

OPTIONAL

Note: at least one of <doi> and <curating_facility> must be supplied

The full, formal name of the external (to PDS) agency or facility that maintains and distributes the product(s) referenced should be included here, if at all possible. This is critical for external sources not associated with a DOI.

<description>

OPTIONAL

Use this attribute to provide any additional explanation or information that would be needed or useful to a user who is attempting to locate the source being referenced. UTF-8 characters beyond the ASCII character set may be used (letters with diacritical marks, for example).