Difference between revisions of "Filling Out the DD Attribute Class"

From The SBN Wiki
Jump to navigation Jump to search
(Creation - Safety Save)
(Creation - Safety Save)
Line 57: Line 57:
 
''OPTIONAL''
 
''OPTIONAL''
  
Sometimes a picture really is worth a thousand or so words.  If you are defining an attribute that, for example, is related to temperature sensors located around the spacecraft, it could be particularly useful to users if the definition liked to an image file that actually pointed to the physical locations referenced.  To do that, label the image as a PDS product and include it in the documentation, then use this class to reference the image from this definition.
+
Sometimes a picture really is worth a thousand or so words.  If you are defining an attribute that, for example, is related to temperature sensors located around the spacecraft, it could be particularly helpful to users if the definition linked to an image file that actually pointed to the physical locations referenced.  To do that, label the image as a PDS product and include it in the documentation, then use this class to reference the image from this definition.
  
Use this when there is a positive and unique benefit to linking to the cross-reference every time the definition is displayed, as in the case above.  It would be more distracting than helpful, for example, to link every calibration-related keyword to a calibration document.  
+
Use this when there is a positive and unique benefit to linking to the cross-referenced every time the definition is displayed, as in the case above.  It would be more distracting than helpful, for example, to link every calibration-related keyword to a calibration document.  
  
=== <lid_reference> ===
+
This is filled out the same way as in [[Filling_Out_the_Reference_List_Classes#.3CInternal_Reference.3E|Filling Out the Reference List Classes - <Internal_Reference>]], except that the ''&lt;reference_type&gt;'' attribute must have the value '''LDD_to_Source'''. 
  
''OPTIONAL'' (but see description)
+
'''''Note'':''' The ''&lt;reference_type&gt;'' value is not actually validated by the PDS common namespace Schematron file, but using another value can lead to complications down the road.  So be careful about getting this value right - including capitalization.  You'll have to check it by eye.
 
 
=== <lidvid_reference> ===
 
 
 
''OPTIONAL'' (but see description)
 
 
 
=== <reference_type> ===
 
 
 
''REQUIRED''
 
 
 
=== <comment> ===
 
 
 
''OPTIONAL''
 
  
 
== <Terminological_Entry> ==
 
== <Terminological_Entry> ==

Revision as of 16:58, 26 March 2015

<name>

REQUIRED

This is the tag name that you'll use in labels to identify this attribute. Tag names do not have to be unique, and in fact there may be times when you specifically decide to define two different versions of the same tag name - for example, to have different unit types or separate enumerated value lists in different contexts.

<version_id>

REQUIRED

This is a version specific to this attribute definition. Use it to track progress on specific definitions independently of the dictionary as a whole. There are no specific format requirements on this version, and it is not required to have any specific relationship to the dictionary version_id. In other words, you have a fair amount of freedom to define a versioning systems appropriate to your development environment and circumstances.

<local_identifier>

REQUIRED

The identifier must be unique within this dictionary. This is the ID you will use to add this attribute to classes, and this is why you can have two or more attributes with the same <name> but different definitions - the unique <local_identifier> distinguished them.

<nillable_flag>

REQUIRED

The PDS shared namespaces follow this convention: If an attribute is required to appear in a class, but there is a reasonable case in which the attribute might not exist (lost data, or it is not a logically applicable concept in certain contexts, etc.), then the attribute may be nillable. "Nillable means that the attribute is still present in the label, but it is explicitly declared to be "nil" and a reason for that is given.

For example, if you defined an attribute call exposure_command that would normally be required in all labels, but might be null because of a known data glitch, then you can declare it null in any particular label by doing this:

  <exposure_command xsi:nil="true" nil_reason="missing"/>

or this, which is an alternate but equivalent syntax:

  <exposure_command xsi:nil="true" nil_reason="missing"></exposure_command>

In PDS shared namespaces, an attribute can either be optional or nillable, but is never both in the same context. The list of nil_reason values is in the pds: namespace Schematron file.

Value values for nillable_flag are true and false.

<submitter_name>

REQUIRED

This is the name of the person responsible for this particular attribute definition. In large projects, dictionary development duties may be delegated to several individuals, and this field enables tracking that responsibility. In small projects, this will be the same as (or equivalent to) the <full_name> value in the <Ingest_LDD> parameters at the top of the file.

<definition>

REQUIRED

This is the human-readable description of the attribute meaning. This will be reviewed by the external reviewers, and will also be available to user for the life of the data set (50 years, at least). As far as reasonable, the definition should not require intimate knowledge of the mission, instrument, or data to understand. So be careful using abbreviations, make cross-references fairly specific, and while you can assume the user looking up this definition is probably looking at a related data label, try not to assume he's read and remembered all the collection documentation.

<comment>

OPTIONAL

This is an optional free-text field for additional comments. These are not transferred to the final dictionary files, so they should only be used for comments that are not relevant to end users. You may want to include notes to yourself, for example, or remarks about completion status or team members providing needed information.

<Internal_Reference>

OPTIONAL

Sometimes a picture really is worth a thousand or so words. If you are defining an attribute that, for example, is related to temperature sensors located around the spacecraft, it could be particularly helpful to users if the definition linked to an image file that actually pointed to the physical locations referenced. To do that, label the image as a PDS product and include it in the documentation, then use this class to reference the image from this definition.

Use this when there is a positive and unique benefit to linking to the cross-referenced every time the definition is displayed, as in the case above. It would be more distracting than helpful, for example, to link every calibration-related keyword to a calibration document.

This is filled out the same way as in Filling Out the Reference List Classes - <Internal_Reference>, except that the <reference_type> attribute must have the value LDD_to_Source.

Note: The <reference_type> value is not actually validated by the PDS common namespace Schematron file, but using another value can lead to complications down the road. So be careful about getting this value right - including capitalization. You'll have to check it by eye.

<Terminological_Entry>

OPTIONAL

<name>

REQUIRED

<definition>

REQUIRED

<language>

REQUIRED

<preferred_flag>

REQUIRED

<role>

OPTIONAL

<External_Reference_Extended>

OPTIONAL

<doi>

OPTIONAL

<reference_text>

REQUIRED

<description>

OPTIONAL

<name>

OPTIONAL

<url>

OPTIONAL

<DD_Value_Domain>

REQUIRED

<enumeration_flag>

REQUIRED

<value_data_type>

REQUIRED

<formation_rule>

OPTIONAL

<minimum_characters>

OPTIONAL

<maximum_characters>

OPTIONAL

<minimum_value>

OPTIONAL

<maximum_value>

OPTIONAL

<pattern>

OPTIONAL

<unit_of_measure_type>

OPTIONAL

<specified_unit_id>

OPTIONAL

<DD_Permissible_Value>

OPTIONAL

<value>

REQUIRED

<value_meaning>

REQUIRED

<Terminological_Entry>

OPTIONAL