Recommended Tools

• XML Editor: Oxygen XML Editor, IntelliJ IDEA, VS Code with XML extensions
• Validation: PDS4 Validate Tool (available from https://nasa-pds.github.io/validate/)
• LDDTool: Latest version of LDDTool (see installation guide)

File Organization

The Ingest_LDD file must follow a specific ordering:

1. Ingest_LDD header - Dictionary metadata (namespace, version, steward)
2. DD_Attribute definitions - All attributes must be defined first
3. DD_Class definitions - Classes defined after all attributes
4. DD_Rule definitions (optional) - Schematron validation rules
5. Property_Maps (optional) - Terminological mappings

Important ordering rules:

• All attributes must be defined before any class definitions
• No enforced ordering within the attribute or class sections
• Classes can reference other classes that haven't been defined yet
• Attributes and classes can be in any order within their respective sections

Best practices for maintainability:

• Organize attributes alphabetically or by functional grouping
• Define lower-level subclasses before their containing classes
• Group related attributes and classes together
• Add XML comments to mark major sections

Naming Conventions

PDS discipline namespaces follow these conventions:

Attributes:

• Use lowercase with underscores separating words
• Follow English grammar word order
• Examples: horizontal_display_axis, instrument_compression_ratio

Classes:

• Use initial capitalization (PascalCase) with underscores separating words
• Follow English grammar word order
• Examples: Display_Settings, Instrument_Compression_Parameters

General rules:

• ASCII characters only (no accented characters, emoji, etc.)
• Abbreviations should be avoided unless widely recognized
• Be consistent with PDS4 common dictionary naming patterns
• Use descriptive, self-documenting names

While not strictly mandatory, adhering to these conventions improves readability, consistency, and acceptance during peer review.

Grouping Attributes into Classes

You have flexibility in how you organize attributes into classes and subclasses. Consider these approaches:

Functional grouping - Group attributes by their purpose or use:

<DD_Class>
  <name>Display_Settings</name>
  <definition>Settings for displaying array data on a device.</definition>
  <!-- Groups all display-related attributes -->
</DD_Class>

Hierarchical grouping - Create subclasses for logical containment:

<DD_Class>
  <name>Observation_Parameters</name>
  <DD_Association>
    <local_identifier>Timing_Parameters</local_identifier>
    <reference_type>component_of</reference_type>
  </DD_Association>
  <DD_Association>
    <local_identifier>Instrument_Settings</local_identifier>
    <reference_type>component_of</reference_type>
  </DD_Association>
</DD_Class>

Best practices:

• Reuse functional groupings from PDS3 labels when available
• Make all attributes belong to some dictionary class rather than standalone elements
• Keep class hierarchies shallow (typically 2-3 levels maximum)
• Group attributes that are logically related or always used together

Documentation Requirements

All attribute definitions must be substantive and complete:

Critical requirements:

• Provide clear, complete definitions that explain the purpose and usage
• If an attribute has a unit of measure, you must include the unit_of_measure_type in the definition
• Avoid “TBD” placeholders - these cause problems during peer review
• All definitions are subject to external peer review by domain experts

Good definition example:

<DD_Attribute>
  <name>instrument_compression_ratio</name>
  <definition>The instrument_compression_ratio attribute specifies the ratio
  of the size of uncompressed image data to the size of compressed image data
  for on-board compression. A value of 1.0 indicates no compression.</definition>
  <DD_Value_Domain>
    <enumeration_flag>false</enumeration_flag>
    <value_data_type>ASCII_Real</value_data_type>
    <unit_of_measure_type>Units_of_None</unit_of_measure_type>
  </DD_Value_Domain>
</DD_Attribute>

Poor definition example (avoid this):

<DD_Attribute>
  <name>compression_ratio</name>
  <definition>TBD</definition>  <!-- NOT ACCEPTABLE -->
</DD_Attribute>

Keep It Simple

Excessive internal complexity in local dictionaries should be avoided:

Problems with complex dictionaries:

• Increases user confusion and implementation difficulty
• Creates dependencies between different dictionary stewards
• May become unsupportable after mission end
• Makes validation and testing harder

Types of complexity to avoid:

• Deep class hierarchies (more than 3-4 levels)
• Excessive cross-namespace references
• Complicated choice lists with many alternatives
• Overly restrictive Schematron rules

When complexity seems necessary:

• Consult your PDS node consultant before implementation
• Consider whether the complexity is truly required
• Document the rationale for complex structures
• Provide clear usage examples

Cross-Namespace Dependencies

When your dictionary references classes or attributes from other namespaces:

Considerations:

• Creates dependency on external stewards
• May require coordination for changes
• Can break if referenced namespace changes
• Adds complexity for users

Best practices:

• Minimize cross-namespace references when possible
• Document all external dependencies clearly
• Coordinate with external namespace stewards
• Test with multiple IM versions

Required Attributes

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1P00.sch"
  schematypens="http://purl.oclc.org/dsdl/schematron"?>
<Ingest_LDD xmlns="http://pds.nasa.gov/pds4/pds/v1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pds.nasa.gov/pds4/pds/v1
    https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1P00.xsd">

  <name>Example Dictionary</name>
  <ldd_version_id>1.0.0.0</ldd_version_id>
  <dictionary_type>Discipline</dictionary_type>
  <full_name>Your Name</full_name>
  <steward_id>img</steward_id>
  <namespace_id>example</namespace_id>

  <comment>Brief description of the dictionary's purpose and scope.</comment>

  <last_modification_date_time>2025-01-15T12:00:00Z</last_modification_date_time>

  <!-- DD_Attribute definitions go here -->

  <!-- DD_Class definitions go here -->

  <!-- DD_Rule definitions go here (optional) -->

</Ingest_LDD>

Key Attributes Explained

Namespace ID rules:

• Must be unique across all PDS4 dictionaries
• Should be 2-8 characters
• Use lowercase letters only
• Should be mnemonic (related to dictionary purpose)

Dictionary type:

• Discipline - For discipline-wide dictionaries (imaging, geometry, spectroscopy)
• Mission - For mission-specific dictionaries (InSight, OSIRIS-REx)

Enumerated Attributes

For attributes with restricted value lists:

<DD_Attribute>
  <name>horizontal_display_direction</name>
  <version_id>1.0</version_id>
  <local_identifier>example.horizontal_display_direction</local_identifier>
  <nillable_flag>false</nillable_flag>
  <submitter_name>Jane Doe</submitter_name>

  <definition>The horizontal_display_direction attribute specifies the
  direction across the screen that data should be displayed.</definition>

  <DD_Value_Domain>
    <enumeration_flag>true</enumeration_flag>
    <value_data_type>ASCII_Short_String_Collapsed</value_data_type>
    <unit_of_measure_type>Units_of_None</unit_of_measure_type>

    <DD_Permissible_Value>
      <value>Left to Right</value>
      <value_meaning>Display elements from left to right, with lowest
      indices at the left edge.</value_meaning>
    </DD_Permissible_Value>

    <DD_Permissible_Value>
      <value>Right to Left</value>
      <value_meaning>Display elements from right to left, with lowest
      indices at the right edge.</value_meaning>
    </DD_Permissible_Value>
  </DD_Value_Domain>
</DD_Attribute>

Key points about enumerated attributes:

• Set enumeration_flag to true
• Define each permissible value with DD_Permissible_Value
• Provide value_meaning for each value
• LDDTool automatically generates Schematron validation for these

Value Data Types

Common PDS4 data types:

Units of Measure

If your attribute has units, specify unit_of_measure_type:

<DD_Value_Domain>
  <enumeration_flag>false</enumeration_flag>
  <value_data_type>ASCII_Real</value_data_type>
  <minimum_value>0.0</minimum_value>
  <maximum_value>360.0</maximum_value>
  <unit_of_measure_type>Units_of_Angle</unit_of_measure_type>
</DD_Value_Domain>

Common unit types:

• Units_of_None - Dimensionless
• Units_of_Length - Meters, kilometers, etc.
• Units_of_Time - Seconds, days, etc.
• Units_of_Angle - Degrees, radians
• Units_of_Mass - Kilograms, grams
• See the PDS4 Data Dictionary for complete list

DD_Association Cardinality

Control whether components are required or optional:

Referencing External Namespaces

Reference attributes/classes from other namespaces:

<DD_Association>
  <!-- Reference attribute from pds namespace -->
  <local_identifier>pds.comment</local_identifier>
  <reference_type>attribute_of</reference_type>
  <minimum_occurrences>0</minimum_occurrences>
  <maximum_occurrences>1</maximum_occurrences>
</DD_Association>

<DD_Association>
  <!-- Reference class from geom namespace -->
  <local_identifier>geom.Coordinate_Space_Definition</local_identifier>
  <reference_type>component_of</reference_type>
  <minimum_occurrences>0</minimum_occurrences>
  <maximum_occurrences>1</maximum_occurrences>
</DD_Association>

Format: namespace_id.element_name

Schematron Rules (DD_Rule)

Define custom validation constraints beyond basic structure:

<DD_Rule>
  <local_identifier>rule_display_settings_required</local_identifier>
  <rule_context>//example:Display_Settings</rule_context>
  <rule_type>Assert</rule_type>

  <DD_Rule_Statement>
    <rule_type>Assert</rule_type>
    <rule_test>example:horizontal_display_axis and example:horizontal_display_direction</rule_test>
    <rule_message>Both horizontal_display_axis and horizontal_display_direction
    are required when Display_Settings is present.</rule_message>
  </DD_Rule_Statement>
</DD_Rule>

Rule types:

• Assert - Condition must be true
• Report - Report when condition is true (for warnings)

Use cases:

• Co-occurrence constraints (if A present, B must be present)
• Value range validation (attribute A > attribute B)
• Cross-element validation
• Conditional requirements

Choice Lists

Allow users to choose between different elements:

<DD_Association>
  <local_identifier>XSChoice#1</local_identifier>
  <reference_type>attribute_of</reference_type>
  <minimum_occurrences>1</minimum_occurrences>
  <maximum_occurrences>1</maximum_occurrences>
</DD_Association>

<!-- Following associations are part of the choice -->
<DD_Association>
  <local_identifier>example.option_a</local_identifier>
  <reference_type>attribute_of</reference_type>
  <minimum_occurrences>1</minimum_occurrences>
  <maximum_occurrences>1</maximum_occurrences>
</DD_Association>

<DD_Association>
  <local_identifier>example.option_b</local_identifier>
  <reference_type>attribute_of</reference_type>
  <minimum_occurrences>1</minimum_occurrences>
  <maximum_occurrences>1</maximum_occurrences>
</DD_Association>

This generates <xs:choice> in the schema, allowing either option_a or option_b.

Restricting External Attributes

Override an attribute from another namespace with tighter constraints:

<DD_Attribute>
  <name>comment</name>
  <version_id>1.0</version_id>
  <!-- This is the full unique identifier of the external attribute -->
  <local_identifier>0001_NASA_PDS_1.pds.Discipline_Area.pds.comment</local_identifier>
  <nillable_flag>false</nillable_flag>
  <submitter_name>Jane Doe</submitter_name>

  <definition>In this context, comment must follow specific format rules...</definition>

  <DD_Value_Domain>
    <enumeration_flag>false</enumeration_flag>
    <value_data_type>ASCII_Short_String_Collapsed</value_data_type>
    <minimum_characters>10</minimum_characters>
    <maximum_characters>255</maximum_characters>
  </DD_Value_Domain>
</DD_Attribute>

Use this technique to:

• Add tighter constraints to generic attributes
• Restrict value ranges
• Change cardinality
• Add enumerated values