Filling Out the DD Attribute Class

From The SBN Wiki
Revision as of 17:37, 26 March 2015 by Raugh (talk | contribs) (Creation - Safety Save)
Jump to navigation Jump to search

<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 illustrated 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 method when there is a positive and unique benefit to linking to the cross-referenced product every time the definition is displayed, as in the case above. It would likely be much 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

The Terminological_Entry class may be used to provide a translation of this definition into a different language. It is intended to be used to support multi-lingual archives. It may not be used to provide alternate and conflicting definitions for the same attribute. Use multiple attributes with the same name and different <DD_Attribute> definitions for creating context-varying definitions for the same attribute name.

Note that you must use a UTF-8 character set for Ingest_LDD files that contain definitions with non-ASCII characters in them. Check your editor settings before you start!

<name>

REQUIRED

This string contains the translation of the <name> attribute of DD_Attribute into the language specified by <language>. It must follow the same rules for names as the <name> field in the main DD_Attribute definition, except that rather than being constrained to using ASCII letters, it may use UTF-8 characters that have the Unicode "alphabetic" property.

<definition>

REQUIRED

This is a free-format text field that contains the translation of the <definition> text of DD_Attribute into the language specified by <language>, following.

<language>

REQUIRED

The English name of the language used for the name and description translations, above. So far, there are only two standard values defined: English, which may be used only if the primary language of the dictionary is not English; and Russian. If you want to see an additional value added to this list, contact your PDS node consultant and make the request.

<preferred_flag>

REQUIRED

If this flag is true, it indicates that this translation of the definition should be preferred over any others that might appear, including the main <definition>. This should never be true for data preparers creating new dictionaries to be archived primarily in the PDS, but as time goes on it may be useful for migrating dictionaries from the archives of the various IPDA partners to archives in other nations, and for international collaborative efforts.

Allowed values are true and false.

<role>

OPTIONAL

This attribute is undocumented. Avoid it.

<External_Reference_Extended>

OPTIONAL

This extended version of the standard <External_Reference> class includes two additional fields to hold a name and URL. SBN will not allow you to reference a URL in a critical archive document like a mission dictionary, so you should treat this class as if it were a standard <External_Reference>, and fill it out the same way as Filling Out the Reference_List Classes - <External_Reference>, but using the class name External_Reference_Extended.

<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