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

From The SBN Wiki
Jump to navigation Jump to search
(Creation - Safety Save)
m ()
 
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
The ''<DD_Attribute>'' class defines a single, specific attribute for use in labels.  Attributes defined using this class are grouped into label classes via ''<DD_Class>'' definitions.  Repeat this class for each specific attribute definition you need to create your local classes.
 +
 +
''Last Update: 29 July 2020 for IM 1.14.0.0 (1E00 schemas)''
 +
 +
 
== <name> ==
 
== <name> ==
  
 
''REQUIRED''
 
''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.
+
This is the tag name that you'll use in labels to identify this attribute.  Tag names are not required to be unique - you can have the same attribute name in different classes with different definitions.  This is best used to provide different permissible value lists in different class contexts. In general, it is not a good idea to use the same attribute ''name'' to mean completely different things in different classes. Good organization and bookkeeping on this issue will be essential.  If you accidentally duplicate a tag name, this may produce subtle errors down the line that could be very hard to diagnose.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''There are a couple of major issues with validation, or rather lack thereof, associated with this field:''
 +
* ''The character set is not restricted to ASCII.  Unless you '''know''' the environment you're working in is configured to treat UTF-8 properly '''and''' you know how to get the proper code points into your ''Ingest_LDD'' file for UTF-8 characters, you should avoid UTF-8.  You should probably avoid it anyway for this field.''
 +
* ''The character set is not restricted to letters, numbers, and underscores, or in fact even to printable characters.  A fair number of those currently permitted characters are problematic for processing and should be aggressively avoided.  Character entity substitutions are '''not''' a viable alternative here.''
 +
|}
  
 
== <version_id> ==
 
== <version_id> ==
Line 9: Line 21:
 
''REQUIRED''
 
''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 ''<code>version_id</code>''. In other words, you have a fair amount of freedom to define a versioning systems appropriate to your development environment and circumstances.
+
This is a version specific to this attribute definition.  Use it to track progress on specific definitions independently of the dictionary as a whole. This is required to have the format ''M.n''. SBN strongly recommends you increment the major version number when you make a non-backwards compatible change to your attribute definition, and propagate that change to your dictionary ''&lt;ldd_version_id&gt;''.
  
 
== <local_identifier> ==
 
== <local_identifier> ==
Line 15: Line 27:
 
''REQUIRED''
 
''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 ''&lt;name&gt;'' but different definitions  - the unique ''&lt;local_identifier&gt;'' distinguished them.
+
This identifier ''must'' be unique (among ''&lt;local_identifier&gt;'' values) within this dictionary, and it is restricted to ASCII.  This is the ID you will use to add this attribute to classes.  This attribute can, in fact, have exactly the same value as the ''&lt;name&gt;'' attribute in the same class, provided that no other &lt;local_identifier&gt; has that value.  Some dictionary writers append a prefix related to the containing class or some other circumstance to help with locating attributes and classes for maintenance. This is a particularly good idea when you have attributes with the same name but different definitions (a different permissible value list, for example) in different classes.
  
 
== <nillable_flag> ==
 
== <nillable_flag> ==
Line 21: Line 33:
 
''REQUIRED''
 
''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.   
+
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:
 
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:
<code><pre>
+
::<code><exposure_command xsi:nil="true" nil_reason="missing"/></code>
  <exposure_command xsi:nil="true" nil_reason="missing"/>
 
</pre></code>
 
 
or this, which is an alternate but equivalent syntax:
 
or this, which is an alternate but equivalent syntax:
<code><pre>
+
::<code><exposure_command xsi:nil="true" nil_reason="missing"></exposure_command></code>
  <exposure_command xsi:nil="true" nil_reason="missing"></exposure_command>
+
In PDS discipline 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 <code>pds:</code> namespace Schematron file.
</pre></code>
 
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 <code>pds:</code> namespace Schematron file.
 
  
 
Value values for ''nillable_flag'' are '''''true''''' and '''''false'''''.
 
Value values for ''nillable_flag'' are '''''true''''' and '''''false'''''.
Line 55: Line 63:
 
== <Internal_Reference> ==
 
== <Internal_Reference> ==
  
''OPTIONAL''
+
''OPTIONAL, Repeatable''
  
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.
+
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 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.  
+
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#.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'''.   
 
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'''.   
  
'''''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 capitalizationYou'll have to check it by eye.
+
{| class="wikitable" style="background-color: yellow"
 +
| '''Notes:'''  
 +
* ''There are no ''&lt;reference_type&gt;'' values defined for this class, so it is not yet technically possible to use it.
 +
* ''The ''LID''/''LIDVID'' reference values in this class are not currently validatedType carefully.''
 +
|}
  
 
== <Terminological_Entry> ==
 
== <Terminological_Entry> ==
  
''OPTIONAL''
+
''OPTIONAL, Repeatable''
 +
 
 +
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 ''&lt;DD_Attribute&gt;'' 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> ===
 
=== <name> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This string contains the translation of the ''&lt;name&gt;'' attribute of ''DD_Attribute'' into the language specified by ''&lt;language&gt;''.  It should be a valid XML ID string (this is not validated); it may contain UTF-8 characters that have the Unicode "alphabetic" property.
  
 
=== <definition> ===
 
=== <definition> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This is a free-format text field that contains the translation of the ''&lt;definition&gt;'' text of ''DD_Attribute'' into the language specified by ''&lt;language&gt;'', following.
  
 
=== <language> ===
 
=== <language> ===
  
 
''REQUIRED''
 
''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> ===
 
=== <preferred_flag> ===
Line 85: Line 107:
 
''REQUIRED''
 
''REQUIRED''
  
=== <role> ===
+
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 ''&lt;definition&gt;''.  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.
  
''OPTIONAL''
+
Allowed values are '''true''' and '''false'''.
  
=== <External_Reference_Extended> ===
+
=== <skos_relation_name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <doi> ====
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''Note:''' ''This attribute is not well-defined, nor is its use.  If you want to include [https://www.w3.org/2004/02/skos/ SKOS] information in your attribute definition, please contact your PDS node consultant.
 +
|}
 +
 
 +
=== <instance_id> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <reference_text> ====
+
This attribute, if it exists, is defined to contain "an identifier for the single occurrence of an object, for instance an XPath".  It exists as a handle for applications making use of ''Terminological_Entry'' information for advanced or location-specific processing. Routine dictionary operations can carry on happily without it, so you can omit it unless you have a specific use for it in mind - in which case you should be talking with your PDS node consultant.
  
''REQUIRED''
+
=== <External_Reference_Extended> ===
 
 
==== <description> ====
 
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <name> ====
+
This extended version of the standard ''&lt;External_Reference&gt;'' 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/project/proposal dictionary, so you should treat this class as if it were a standard ''&lt;External_Reference&gt;'', and fill it out the same way as [[Filling_Out_the_Reference_List_Classes#.3CExternal_Reference.3E|Filling Out the Reference_List Classes - <External_Reference>]], but using the class name ''External_Reference_Extended''.  Clarifying ''&lt;comment&gt;'' attributes are strongly encouraged.
  
''OPTIONAL''
+
== <DD_Value_Domain> ==
  
==== <url> ====
+
''REQUIRED''
  
''OPTIONAL''
+
The ''DD_Value_Domain'' class is used to provide constraints on what can appear as a value of the attribute being defined.  The more specific you can be here, the more validation can be performed automatically for you in your labels, so SBN recommends you take maximum advantage of the opportunity.
  
== <DD_Value_Domain> ==
 
''REQUIRED''
 
 
=== <enumeration_flag> ===
 
=== <enumeration_flag> ===
 +
 
''REQUIRED''
 
''REQUIRED''
 +
 +
If ''true'', this flag indicates that the attribute has an enumerated value list, which will be defined subsequently.  Enumerated value lists are an excellent way to catch and eliminate both human variation and typos in things like names and abbreviations used across instrument teams.
 +
 +
Valid values are '''true''' and '''false'''.
 +
 
=== <value_data_type> ===
 
=== <value_data_type> ===
 +
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This field defines the base data type of the attribute.  It must be logically consistent with whatever additional constraints you add - so, for example, don't use a numeric data type that can't be less than zero and then try to extend that type by setting ''&lt;minimum_value&gt;'' to "-90".  This sort of conflict is unlikely to be flagged by validators or ''LDDTool'', and will likely lead to very confusing validation messages for your product labels.
 +
 +
Valid data types are:
 +
:::{|
 +
|-
 +
| valign="top" |
 +
* [[PDS4 Character Data Type Definitions#ASCII_AnyURI|ASCII_AnyURI]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_BibCode|ASCII_BibCode]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Boolean|ASCII_Boolean]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_DOI|ASCII_DOI]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_DOY|ASCII_Date_DOY]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_Time_DOY|ASCII_Date_Time_DOY]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_Time_DOY_UTC|ASCII_Date_Time_DOY_UTC]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_YMD|ASCII_Date_YMD]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_Time_YMD|ASCII_Date_Time_YMD]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Date_Time_YMD_UTC|ASCII_Date_Time_YMD_UTC]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Directory_Path_Name|ASCII_Directory_Path_Name]]
 +
| valign="top" |
 +
* [[PDS4 Character Data Type Definitions#ASCII_File_Name|ASCII_File_Name]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_File_Specification_Name|ASCII_File_Specification_Name]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Integer|ASCII_Integer]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_LID|ASCII_LID]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_LIDVID|ASCII_LIDVID]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_LIDVID_LID|ASCII_LIDVID_LID]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_MD5_Checksum|ASCII_MD5_Checksum]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_NonNegative_Integer|ASCII_NonNegative_Integer]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Numeric_Base2|ASCII_Numeric_Base2]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Numeric_Base8|ASCII_Numeric_Base8]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Numeric_Base16|ASCII_Numeric_Base16]]
 +
| valign="top" |
 +
* [[PDS4 Character Data Type Definitions#ASCII_Real|ASCII_Real]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Short_String_Collapsed|ASCII_Short_String_Collapsed]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Short_String_Preserved|ASCII_Short_String_Preserved]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Text_Collapsed|ASCII_Text_Collapsed]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Text_Preserved|ASCII_Text_Preserved]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_Time|ASCII_Time]]
 +
* [[PDS4 Character Data Type Definitions#ASCII_VID|ASCII_VID]]
 +
* [[PDS4 Character Data Type Definitions#UTF8_Short_String_Collapsed|UTF8_Short_String_Collapsed]]
 +
* [[PDS4 Character Data Type Definitions#UTF8_Short_String_Preserved|UTF8_Short_String_Preserved]]
 +
* [[PDS4 Character Data Type Definitions#UTF8_Text_Collapsed|UTF8_Text_Preserved]]
 +
* [[PDS4 Character Data Type Definitions#UTF8_Text_Preserved|UTF8_Text_Preserved]]
 +
|}
 +
 +
The links will take you to descriptions of the various data types.
 +
 
=== <formation_rule> ===
 
=== <formation_rule> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This is a human-readable description of how valid values for this attribute should be formulated.  It might contain, for example, a description of the fields in a spacecraft clock string.  It's a good idea to include this description if you are also using ''&lt;pattern&gt;'' to constrain the field values, to explain what a non-trivial ''pattern'' expression is actually doing.
 +
 
=== <minimum_characters> ===
 
=== <minimum_characters> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
Use this for any non-numeric attribute values that must have a minimum number of characters.  For example, if you are defining a time field that must always be accurate at least to 0.01 seconds, then you can set ''&lt;minimum_characters&gt;'' to "11" as a sanity check.
 +
 +
'''Note''' that unless your attribute is defined with a data type that preserves all white space, leading and trailing white space is not included in the character count for the value length.
 +
 
=== <maximum_characters> ===
 
=== <maximum_characters> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
Use this for any non-numeric attribute values that must have a length restriction in the number of characters.  For example, if want to make sure that a descriptive field you've defined for your labels will never overflow the 2000 characters you've allocated for it in a mission database, you can set ''&lt;maximum_characters&gt;'' to "2000" catch potential overflow cases in validation.
 +
 +
'''Notes:'''
 +
* Unless your attribute is defined with a data type that preserves all white space, leading and trailing white space is not included in the character count for the value length.
 +
* The data types with ''Short_String'' in their names are already constrained to be no more than 255 characters long.
 +
 
=== <minimum_value> ===
 
=== <minimum_value> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
Use this to specify a minimum valid value for a numeric field.  Typically a field described as a count can never be less that zero, for example, so you can specify that via ''&lt;minimum_value&gt;''.
 +
 +
'''If your attribute has a defined ''&lt;unit_of_measure_type&gt;'',''' you should include a ''&lt;specified_unit_id&gt;'' (see following) to define what unit of measure the ''minimum_value'' is in.  You should do this for completeness and to avoid potential future editing errors even if your minimum is zero.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''N.B.:''' ''Use of ''&lt;specified_unit_id&gt;'' is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.
 +
|}
 +
 
=== <maximum_value> ===
 
=== <maximum_value> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
Use this to specify a maximum valid value for a numeric field.  This is useful, for example, if you're defining a keyword that corresponds to a measurement that is physically constrained.  If your instrument can never rotate more than ten degrees off a particular axis, for example, you can specify this via ''&lt;maximum_value&gt;''.
 +
 +
'''If your attribute has a defined ''&lt;unit_of_measure_type&gt;'',''' you should include a ''&lt;specified_unit_id&gt;'' (see following) to define what unit of measure the ''maximum_value'' is in.  You should do this for completeness and to avoid potential future editing errors even if your maximum value is zero.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''N.B.:''' ''Use of ''&lt;specified_unit_id&gt;'' is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.
 +
|}
 +
 
=== <pattern> ===
 
=== <pattern> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
{| class="wikitable" style="background-color: lightcyan"
 +
|
 +
'''Note:''' LDDTool'' cannot determine if your pattern will be syntactically valid in the context of the output XML Schema file.  Therefore, it is essential that any dictionary preparer who is using the ''&lt;pattern&gt;'' attribute check the output XML Schema file for validity ''before'' attempting to use it to create or validate labels.  You can validate the schema using a validating editor or any other XML schema-based validation tool you might have. (It references the PDS4 core schema, so you will need to feed that into the validator as well.)  An invalid pattern in the .xsd file will cause validation failures when attempting to validate a label that will most likely be attributed to a missing or unreadable schema file.''
 +
|}
 +
 +
The ''pattern'' attribute contains a regular expression pattern (using a syntax defined in the XML Schema standard) that is applied during validation to require that values successfully match the pattern.  A ''&lt;pattern&gt;'' to require that an ''ASCII_Integer''-type field has exactly ten digits, for example, would look like this:
 +
 +
::<code><pattern>[0-9]{10}</pattern></code>
 +
 +
Regular expressions are as powerful as they are tricky.  You should plan to test any patterns in your data dictionary pretty thoroughly for both spurious matches and unintended misses.  For a quick summary of the key XML Schema regular expression features, see the [[XML Schema Regular Expressions - Basics]] page on this wiki.  In addition, PDS imposes the following constraints on this attribute:
 +
* It may not be repeated. The work-around for this is to use a single pattern declaration with each desired pattern parenthesized and separated from the others by the alternation bar (' | ').
 +
* Your pattern may not contain non-ASCII characters, even if you specify them by character entity reference.  This effectively prevents detailed pattern validation for any non-ASCII characters, but you can use the standard escape sequences and block escapes recognized by XML Schema (see [[XML Schema Regular Expressions - Basics]]).
 +
 
=== <unit_of_measure_type> ===
 
=== <unit_of_measure_type> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
For  background information on units of measure of PDS4 label attributes, see the short page [[Units_of_Measure|Units of Measure]].  Consistent with the unit handling in the PDS shared namespaces, when you define an attribute with units in your local dictionary you actually associate the attribute with a class of units via this attribute.
 +
 +
'''N.B.:''' If you are defining an attribute that has a natural unit associated with it, you ''must'' specify a unit class for it, and you ''must'' always specify a unit when you use the attribute in a label.  This is a basic and very hard requirement for properly documenting your data.  No short-cuts, please.
 +
 +
The valid values for the attribute are the names of the unit classes defined in the ''<code>pds:</code>'' core namespace:
 +
:::{|
 +
|-
 +
 +
| valign="top" |
 +
* [[Unit_Classes_Standard_Values#Acceleration|Units_of_Acceleration]]
 +
* [[Unit_Classes_Standard_Values#Amount_of_Substance|Units_of_Amount_Of_Substance]]
 +
* [[Unit_Classes_Standard_Values#Angle|Units_of_Angle]]
 +
* [[Unit_Classes_Standard_Values#Angular_Velocity|Units_of_Angular_Velocity]]
 +
* [[Unit_Classes_Standard_Values#Area|Units_of_Area]]
 +
* [[Unit_Classes_Standard_Values#Current|Units_of_Current]]
 +
* [[Unit_Classes_Standard_Values#Energy|Units_of_Energy]]
 +
* [[Unit_Classes_Standard_Values#Force|Units_of_Force]]
 +
* [[Unit_Classes_Standard_Values#Frame_Rate|Units_of_Frame_Rate]]
 +
* [[Unit_Classes_Standard_Values#Frequency|Units_of_Frequency]]
 +
* [[Unit_Classes_Standard_Values#Length|Units_of_Length]]
 +
* [[Unit_Classes_Standard_Values#Map_Scale|Units_of_Map_Scale]]
 +
| valign="top" |
 +
* [[Unit_Classes_Standard_Values#Mass|Units_of_Mass]]
 +
* [[Unit_Classes_Standard_Values#Misc|Units_of_Misc]]
 +
* [[Unit_Classes_Standard_Values#None|Units_of_None]]
 +
* [[Unit_Classes_Standard_Values#Optical_Path_Length|Units_of_Optical_Path_Length]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Resolution_Angular|Units_of_Pixel_Resolution_Angular]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Resolution_Linear|Units_of_Pixel_Resolution_Linear]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Resolution_Map|Units_of_Pixel_Resolution_Map]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Scale_Angular|Units_of_Pixel_Scale_Angular]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Scale_Linear|Units_of_Pixel_Scale_Linear]]
 +
* [[Unit_Classes_Standard_Values#Pixel_Scale_Map|Units_of_Pixel_Scale_Map]]
 +
* [[Unit_Classes_Standard_Values#Pressure|Units_of_Pressure]]
 +
* [[Unit_Classes_Standard_Values#Radiance|Units_of_Radiance]]
 +
| valign="top" |
 +
* [[Unit_Classes_Standard_Values#Rates|Units_of_Rates]]
 +
* [[Unit_Classes_Standard_Values#Solid_Angle|Units_of_Solid_Angle]]
 +
* [[Unit_Classes_Standard_Values#Spectral_Irradiance|Units_of_Spectral_Irradiance]]
 +
* [[Unit_Classes_Standard_Values#Spectral_Radiance|Units_of_Spectral_Radiance]]
 +
* [[Unit_Classes_Standard_Values#Storage|Units_of_Storage]]
 +
* [[Unit_Classes_Standard_Values#Temperature|Units_of_Temperature]]
 +
* [[Unit_Classes_Standard_Values#Time|Units_of_Time]]
 +
* [[Unit_Classes_Standard_Values#Velocity|Units_of_Velocity]]
 +
* [[Unit_Classes_Standard_Values#Voltage|Units_of_Voltage]]
 +
* [[Unit_Classes_Standard_Values#Volume|Units_of_Volume]]
 +
* [[Unit_Classes_Standard_Values#Wavenumber|Units_of_Wavenumber]]
 +
 +
|}
 +
 +
Valid units for each of the types are enumerated on the [[Unit_Classes_Standard_Values|Unit Classes Standard Values]] page on this wiki.
 +
 +
'''''N.B.'':''' If you are preparing data for submission to or review by the SBN, '''''do not''''' define an attribute as having '''Units_of_None'''.  If the value has no units, do not define it with a ''&lt;unit_of_measure_type&gt;''.  If a user might expect an attribute with this ''name'' to have a unit, state why it does not in the ''&lt;definition&gt;''.
 +
 
=== <specified_unit_id> ===
 
=== <specified_unit_id> ===
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
Use this attribute if and only if these two things are both true:
 +
# You have defined a ''&lt;unit_of_measure_type&gt;''.
 +
# You have also defined either a ''&lt;minimum_value&gt;'' or ''&lt;maximum_value&gt;'', or both, for this attribute.
 +
If this is the case, you should ''always'' include this attribute.
 +
 +
The unit indicated is only applied to the minimum or maximum value in the attribute definition, ''not'' to any label value.  Specifically, it is ''not'' a default unit for the attribute.
 +
 +
It means that, for example, you can define a wavelength range using &Aring;ngstroms in your data dictionary, but the labels can use units of nanometers, and the PDS validation tool should be able to deal with the unit difference and make the appropriate check. (''But note that I haven't actually checked if this is true.'')
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''N.B.:'''
 +
* ''Use of ''&lt;specified_unit_id&gt;'' with ''&lt;unit_of_measure_id&gt;'' is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.''
 +
* ''The actual unit of measure provided is not validated against the ''&lt;unit_of_measure&gt;'' unit class.  Please check this manually and type carefully.  You can find a list of valid units for each class on the ''"[[Unit Classes Standard Values]]"'' page of this wiki.''
 +
|}
 +
 
=== <DD_Permissible_Value> ===
 
=== <DD_Permissible_Value> ===
''OPTIONAL''
+
 
 +
''OPTIONAL, Repeatable''
 +
 
 +
This class is used define the enumerated values that are valid for this attribute, with their meanings.  You must repeat this class once for each enumerated value you wish to define.
 +
 
 
==== <value> ====
 
==== <value> ====
 +
 
''REQUIRED''
 
''REQUIRED''
 +
 +
The value string that must be matched ''exactly'' in the labels.  Both case and imbedded whitespace are significant. Do not include any sort of delimiter around the value you're defining; the ''&lt;value&gt;'' and ''&lt;/value&gt;'' tags are the delimiters.
 +
 +
Enumerated values for things like instrument, phase, or target references can be a particularly effective way to a) make sure everyone is using uniform terminology for key parameters, and b) have the validation software hunt down typos in these critical fields.  SBN encourages our data preparers to use enumerated values wherever they can be reasonably applied for these reasons.
 +
 
==== <value_meaning> ====
 
==== <value_meaning> ====
 +
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This should contain a brief, human-readable definition of the meaning of the related value.  So, for example, if your required values are integers representing quality assessments, here's where you say that "O" corresponds to lost data, "1" to questionable data, and so one.  If your enumerated values are mission-specific abbreviations, say for operational modes, here's where you can and should spell out the acronyms.
 +
 +
In general, your enumerated values should be reasonably self-explanatory if the attribute meaning is likely to be significant to a typical end-user who is trying to understand a product label.  The additional explanation in ''&lt;value_meaning&gt;'' should augment the name for users who want a deeper understanding.
 +
 
==== <Terminological_Entry> ====
 
==== <Terminological_Entry> ====
 +
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
As with the main attribute definition, in international collaborations it can be useful to have translations of the standard values and their meanings available in alternate languages.  In those cases, the ''Terminological_Entry'' provides that capability.  It is filled out the same way, and with the same considerations, here as for the ''DD_Attribute'' [[#.3CTerminological_Entry.3E|<Terminological_Entry>]] above.

Latest revision as of 19:55, 29 July 2020

The <DD_Attribute> class defines a single, specific attribute for use in labels. Attributes defined using this class are grouped into label classes via <DD_Class> definitions. Repeat this class for each specific attribute definition you need to create your local classes.

Last Update: 29 July 2020 for IM 1.14.0.0 (1E00 schemas)


<name>

REQUIRED

This is the tag name that you'll use in labels to identify this attribute. Tag names are not required to be unique - you can have the same attribute name in different classes with different definitions. This is best used to provide different permissible value lists in different class contexts. In general, it is not a good idea to use the same attribute name to mean completely different things in different classes. Good organization and bookkeeping on this issue will be essential. If you accidentally duplicate a tag name, this may produce subtle errors down the line that could be very hard to diagnose.

There are a couple of major issues with validation, or rather lack thereof, associated with this field:

  • The character set is not restricted to ASCII. Unless you know the environment you're working in is configured to treat UTF-8 properly and you know how to get the proper code points into your Ingest_LDD file for UTF-8 characters, you should avoid UTF-8. You should probably avoid it anyway for this field.
  • The character set is not restricted to letters, numbers, and underscores, or in fact even to printable characters. A fair number of those currently permitted characters are problematic for processing and should be aggressively avoided. Character entity substitutions are not a viable alternative here.

<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. This is required to have the format M.n. SBN strongly recommends you increment the major version number when you make a non-backwards compatible change to your attribute definition, and propagate that change to your dictionary <ldd_version_id>.

<local_identifier>

REQUIRED

This identifier must be unique (among <local_identifier> values) within this dictionary, and it is restricted to ASCII. This is the ID you will use to add this attribute to classes. This attribute can, in fact, have exactly the same value as the <name> attribute in the same class, provided that no other <local_identifier> has that value. Some dictionary writers append a prefix related to the containing class or some other circumstance to help with locating attributes and classes for maintenance. This is a particularly good idea when you have attributes with the same name but different definitions (a different permissible value list, for example) in different classes.

<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 discipline 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, Repeatable

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.

Notes:
  • There are no <reference_type> values defined for this class, so it is not yet technically possible to use it.
  • The LID/LIDVID reference values in this class are not currently validated. Type carefully.

<Terminological_Entry>

OPTIONAL, Repeatable

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 should be a valid XML ID string (this is not validated); it may contain 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.

<skos_relation_name>

OPTIONAL

Note: This attribute is not well-defined, nor is its use. If you want to include SKOS information in your attribute definition, please contact your PDS node consultant.

<instance_id>

OPTIONAL

This attribute, if it exists, is defined to contain "an identifier for the single occurrence of an object, for instance an XPath". It exists as a handle for applications making use of Terminological_Entry information for advanced or location-specific processing. Routine dictionary operations can carry on happily without it, so you can omit it unless you have a specific use for it in mind - in which case you should be talking with your PDS node consultant.

<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/project/proposal 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. Clarifying <comment> attributes are strongly encouraged.

<DD_Value_Domain>

REQUIRED

The DD_Value_Domain class is used to provide constraints on what can appear as a value of the attribute being defined. The more specific you can be here, the more validation can be performed automatically for you in your labels, so SBN recommends you take maximum advantage of the opportunity.

<enumeration_flag>

REQUIRED

If true, this flag indicates that the attribute has an enumerated value list, which will be defined subsequently. Enumerated value lists are an excellent way to catch and eliminate both human variation and typos in things like names and abbreviations used across instrument teams.

Valid values are true and false.

<value_data_type>

REQUIRED

This field defines the base data type of the attribute. It must be logically consistent with whatever additional constraints you add - so, for example, don't use a numeric data type that can't be less than zero and then try to extend that type by setting <minimum_value> to "-90". This sort of conflict is unlikely to be flagged by validators or LDDTool, and will likely lead to very confusing validation messages for your product labels.

Valid data types are:

The links will take you to descriptions of the various data types.

<formation_rule>

OPTIONAL

This is a human-readable description of how valid values for this attribute should be formulated. It might contain, for example, a description of the fields in a spacecraft clock string. It's a good idea to include this description if you are also using <pattern> to constrain the field values, to explain what a non-trivial pattern expression is actually doing.

<minimum_characters>

OPTIONAL

Use this for any non-numeric attribute values that must have a minimum number of characters. For example, if you are defining a time field that must always be accurate at least to 0.01 seconds, then you can set <minimum_characters> to "11" as a sanity check.

Note that unless your attribute is defined with a data type that preserves all white space, leading and trailing white space is not included in the character count for the value length.

<maximum_characters>

OPTIONAL

Use this for any non-numeric attribute values that must have a length restriction in the number of characters. For example, if want to make sure that a descriptive field you've defined for your labels will never overflow the 2000 characters you've allocated for it in a mission database, you can set <maximum_characters> to "2000" catch potential overflow cases in validation.

Notes:

  • Unless your attribute is defined with a data type that preserves all white space, leading and trailing white space is not included in the character count for the value length.
  • The data types with Short_String in their names are already constrained to be no more than 255 characters long.

<minimum_value>

OPTIONAL

Use this to specify a minimum valid value for a numeric field. Typically a field described as a count can never be less that zero, for example, so you can specify that via <minimum_value>.

If your attribute has a defined <unit_of_measure_type>, you should include a <specified_unit_id> (see following) to define what unit of measure the minimum_value is in. You should do this for completeness and to avoid potential future editing errors even if your minimum is zero.

N.B.: Use of <specified_unit_id> is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.

<maximum_value>

OPTIONAL

Use this to specify a maximum valid value for a numeric field. This is useful, for example, if you're defining a keyword that corresponds to a measurement that is physically constrained. If your instrument can never rotate more than ten degrees off a particular axis, for example, you can specify this via <maximum_value>.

If your attribute has a defined <unit_of_measure_type>, you should include a <specified_unit_id> (see following) to define what unit of measure the maximum_value is in. You should do this for completeness and to avoid potential future editing errors even if your maximum value is zero.

N.B.: Use of <specified_unit_id> is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.

<pattern>

OPTIONAL

Note: LDDTool cannot determine if your pattern will be syntactically valid in the context of the output XML Schema file. Therefore, it is essential that any dictionary preparer who is using the <pattern> attribute check the output XML Schema file for validity before attempting to use it to create or validate labels. You can validate the schema using a validating editor or any other XML schema-based validation tool you might have. (It references the PDS4 core schema, so you will need to feed that into the validator as well.) An invalid pattern in the .xsd file will cause validation failures when attempting to validate a label that will most likely be attributed to a missing or unreadable schema file.

The pattern attribute contains a regular expression pattern (using a syntax defined in the XML Schema standard) that is applied during validation to require that values successfully match the pattern. A <pattern> to require that an ASCII_Integer-type field has exactly ten digits, for example, would look like this:

<pattern>[0-9]{10}</pattern>

Regular expressions are as powerful as they are tricky. You should plan to test any patterns in your data dictionary pretty thoroughly for both spurious matches and unintended misses. For a quick summary of the key XML Schema regular expression features, see the XML Schema Regular Expressions - Basics page on this wiki. In addition, PDS imposes the following constraints on this attribute:

  • It may not be repeated. The work-around for this is to use a single pattern declaration with each desired pattern parenthesized and separated from the others by the alternation bar (' | ').
  • Your pattern may not contain non-ASCII characters, even if you specify them by character entity reference. This effectively prevents detailed pattern validation for any non-ASCII characters, but you can use the standard escape sequences and block escapes recognized by XML Schema (see XML Schema Regular Expressions - Basics).

<unit_of_measure_type>

OPTIONAL

For background information on units of measure of PDS4 label attributes, see the short page Units of Measure. Consistent with the unit handling in the PDS shared namespaces, when you define an attribute with units in your local dictionary you actually associate the attribute with a class of units via this attribute.

N.B.: If you are defining an attribute that has a natural unit associated with it, you must specify a unit class for it, and you must always specify a unit when you use the attribute in a label. This is a basic and very hard requirement for properly documenting your data. No short-cuts, please.

The valid values for the attribute are the names of the unit classes defined in the pds: core namespace:

Valid units for each of the types are enumerated on the Unit Classes Standard Values page on this wiki.

N.B.: If you are preparing data for submission to or review by the SBN, do not define an attribute as having Units_of_None. If the value has no units, do not define it with a <unit_of_measure_type>. If a user might expect an attribute with this name to have a unit, state why it does not in the <definition>.

<specified_unit_id>

OPTIONAL

Use this attribute if and only if these two things are both true:

  1. You have defined a <unit_of_measure_type>.
  2. You have also defined either a <minimum_value> or <maximum_value>, or both, for this attribute.

If this is the case, you should always include this attribute.

The unit indicated is only applied to the minimum or maximum value in the attribute definition, not to any label value. Specifically, it is not a default unit for the attribute.

It means that, for example, you can define a wavelength range using Ångstroms in your data dictionary, but the labels can use units of nanometers, and the PDS validation tool should be able to deal with the unit difference and make the appropriate check. (But note that I haven't actually checked if this is true.)

N.B.:

  • Use of <specified_unit_id> with <unit_of_measure_id> is not currently validated. Omitting it can lead to subtle or even undetected validation failures down the road.
  • The actual unit of measure provided is not validated against the <unit_of_measure> unit class. Please check this manually and type carefully. You can find a list of valid units for each class on the "Unit Classes Standard Values" page of this wiki.

<DD_Permissible_Value>

OPTIONAL, Repeatable

This class is used define the enumerated values that are valid for this attribute, with their meanings. You must repeat this class once for each enumerated value you wish to define.

<value>

REQUIRED

The value string that must be matched exactly in the labels. Both case and imbedded whitespace are significant. Do not include any sort of delimiter around the value you're defining; the <value> and </value> tags are the delimiters.

Enumerated values for things like instrument, phase, or target references can be a particularly effective way to a) make sure everyone is using uniform terminology for key parameters, and b) have the validation software hunt down typos in these critical fields. SBN encourages our data preparers to use enumerated values wherever they can be reasonably applied for these reasons.

<value_meaning>

REQUIRED

This should contain a brief, human-readable definition of the meaning of the related value. So, for example, if your required values are integers representing quality assessments, here's where you say that "O" corresponds to lost data, "1" to questionable data, and so one. If your enumerated values are mission-specific abbreviations, say for operational modes, here's where you can and should spell out the acronyms.

In general, your enumerated values should be reasonably self-explanatory if the attribute meaning is likely to be significant to a typical end-user who is trying to understand a product label. The additional explanation in <value_meaning> should augment the name for users who want a deeper understanding.

<Terminological_Entry>

OPTIONAL

As with the main attribute definition, in international collaborations it can be useful to have translations of the standard values and their meanings available in alternate languages. In those cases, the Terminological_Entry provides that capability. It is filled out the same way, and with the same considerations, here as for the DD_Attribute <Terminological_Entry> above.