Quick Start

LDDTool is the command-line interface for the PDS4 Information Model document generation tool (DMDocument.jar). It processes Ingest_LDD XML files to generate PDS4 schemas, documentation, and data dictionaries.

Basic syntax:

$ lddtool-16.0.0/bin/lddtool [OPTIONS] [INPUT_FILES...]

Most common usage:

# Generate master PDS4 schemas for the current IM version
$ lddtool -p

# Process a local data dictionary with JSON output
$ lddtool -lpJ PDS4_EXAMPLE_IngestLDD.xml

# Generate with a specific IM version
$ lddtool -lpJ -V 1O00 PDS4_EXAMPLE_IngestLDD.xml

Get help or version information:

$ lddtool -h
$ lddtool -v

Command-Line Reference

These flags control what output files are generated:

Note: Multiple output flags can be combined in a single command (e.g., -lpJD to process an LDD and generate both JSON and DocBook outputs).

These flags modify how LDDTool processes the input:

These flags display information and then exit:

Supported IM Versions:

LDDTool supports all IM versions back to 1B00

Example:

$ lddtool -lpJ -V 1N00 PDS4_IMG_IngestLDD.xml


FILE1 FILE2 ...

One or more Ingest_LDD XML files to process. The .xml extension is assumed if not provided.

Multiple file behavior:

• When multiple files are specified, the first files are considered reference dictionaries
• The last file is treated as the primary local data dictionary
• This allows you to process an LDD that depends on classes/attributes from another LDD

LDDTool generates output files with the following extensions:

Common Use Cases

Generate the core PDS4 schemas for the current IM version:

$ lddtool -p

This creates all the master PDS4 schemas without processing any local dictionaries. Output goes to the PDS4_PDS_1P00/ directory (or appropriate version directory).

Process an Ingest_LDD file to generate schemas for a local dictionary:

$ lddtool -lp PDS4_IMG_IngestLDD.xml

This generates:

• XSD schema file
• Schematron validation file
• Label file
• CSV data dictionary
• Process report

Generate an LDD using an older IM version:

$ lddtool -lpJ -V 1N00 PDS4_GEOM_IngestLDD.xml

This is useful when you need to maintain compatibility with a specific IM version or generate schemas for archival purposes.

Generate JSON representation of the data dictionary:

$ lddtool -lpJ PDS4_CART_IngestLDD.xml

Include all namespaces in JSON output:

$ lddtool -lpJa PDS4_CART_IngestLDD.xml

Combine flags to generate multiple outputs in one run:

$ lddtool -lpJD1 PDS4_SPECTRAL_IngestLDD.xml

This generates:

• Standard outputs (XSD, SCH, XML, CSV, TXT)
• JSON output (-J)
• DocBook documentation (-D)
• IM Specification document (-1)

Version Information

You can view the version number for the executable:

$ lddtool-16.0.0/bin/lddtool -v

LDDTool Version: 16.0.0
Built with IM Version: 1.25.0.0 (1P00)
Build Date: ${build.date}  # or 'YYYY-MM-DD HH:MM:SS' if no macro available
Configured IM Versions: [1P00, 1O00, 1N00, 1M00, 1L00, 1K00, 1J00, 1I00, 1H00, 1G00, 1F00, 1E00, 1D00, 1C00, 1B10, 1B00]

If this does not execute successfully, please return to the installation guide and ensure the software was installed correctly, or contact PDS Operator for assistance.

Running LDDTool on Example Files

To test out running LDDTool, download an existing LDD from the PDS Data Dictionaries repo. A couple examples:

• IMG Discipline LDD - https://github.com/pds-data-dictionaries/ldd-img/blob/master/src/PDS4_IMG_IngestLDD.xml
• GEOM Discipline LDD - https://github.com/pds-data-dictionaries/ldd-geom/blob/master/src/PDS4_GEOM_IngestLDD.xml

To execute, run:

lddtool -lp PDS4_IMG_IngestLDD.xml`

Expected Results

The example lddtool command above will generate a total of five output files in addition to the .out listing file. The files will all have the same lddtool-generted names but different extensions. Here are those extensions, in approximate order of usefulness:

• .xsd: This is the XML Schema file that you will reference in your labels when you want to use classes from this dictionary.
• .sch: This is the Schematron file that you will also reference in your labels when you want to use classes from this dictionary.
• .csv: This is a CSV-formatted summary of the dictionary contents. You might find this a useful way to review the results if you're averse to reading schema and don't have labels already written to exercise the newly-produced schemas. You might also find this to be a useful file for passing to reviewers who want to see class and attribute definitions - though maybe with a little editing first.
• .xml: This is a label for the XML Schema and Schematron files; probably only useful as a template. SBN strongly recommends that rather than creating a label from scratch each time, you modify an existing label at reasonable intervals in order to maintain a <Modification_History> within the label that accurately reflects the development history of the dictionary (as any other product label should for an archival product). At the very least, the schema label should be modified to identify the unique origin and application of the dictionary files it describes. Trying to get the unmodified label produced here through an SBN review is unlikely to be successful.

Checking for Success

If you compare the output files from the above commands to what came in the example zip file, you should see differences in date stamps and local paths, but otherwise nothing else. Mage sure your option string is -lp (lowercase letter “ell”), or you will get a slightly different set of output files or a different namespace definition in the output schemas.

If you run the tool on your own input file, the first thing to check is the program output listing, which will scroll past on your screen if you don't redirect it to a file. The last line of that listing should look like this:

   >>info    - LDDTOOL Exit

This indicates at least some measure of success. Depending on how complex your input file is, there will be a few dozen to a few hundred “INFO” lines containing messages about various override conditions. This is normal. It should not contain any “ERROR” lines or lines beginning with >>error. These indicate some sort of failure. There may be also be “WARNING” lines that look like this:

   WARNING  Header:  - New steward has been specified:sbn
   WARNING  Header:  - New namespace id has been specified:ex

unless you are updating a dictionary that is already known to LDDTool. Other “WARNING” statements, however, are problematic and should be investigated.

Once you've verified expected output, you should be good to go.

Generating Discipline LDDs

A discipline level LDD is generated by running LDDTool on a data dictionary definition file that has the attribute dictionary_type set to the value “Discipline”.

Basic command:

$ lddtool -lpd PDS4_EXAMPLE_IngestLDD.xml

The -d flag indicates this is a discipline dictionary (omits “mission” from namespace).

Instructions for creating Ingest_LDD files:

See the Creating the Ingest LDD Dictionary Input File guide for complete instructions and examples on creating data dictionary definition files (Ingest_LDD.xml files).

Generating Mission LDDs

A mission level LDD is generated by running LDDTool on a data dictionary definition file that has the attribute dictionary_type set to the value “Mission” (note: the documentation previously said “Misison” which was a typo).

Basic command:

$ lddtool -lp PDS4_MISSION_IngestLDD.xml

Mission dictionaries do not use the -d flag, as they are mission-specific by definition.

Instructions for creating Ingest_LDD files:

See the Creating the Ingest LDD Dictionary Input File guide for complete instructions and examples on creating data dictionary definition files (Ingest_LDD.xml files).

Generating LDDs with Specific PDS4 Versions

LDDTool is a reflection of the PDS4 Information Model (IM), and in turn, has a major build in sync with the PDS4 Build Schedule (every 6 months).

By default, LDDTool builds with the latest version of the IM (currently 1P00 / IM v1.25.0.0). As of LDDTool v12.0.0, it can generate LDDs for older versions of the IM using the -V flag.

Syntax:

  -V <version>, --pds4-version <version>

Example:

  $ lddtool -lpJ -V 1N00 PDS4_IMG_IngestLDD.xml

This generates the IMG LDD using IM version 1N00 (Build 14.0, September 2024) instead of the current version.

When to use older IM versions:

• Maintaining compatibility with existing data products validated against a specific IM version
• Generating schemas for archival purposes
• Supporting missions that haven't yet upgraded to the latest IM version
• Testing dictionary changes across multiple IM versions

See the IM Version Selection section above for the complete list of supported versions.

Common Errors

The common failures encountered at this point come from system references not resolving. Here are the most likely suspects:

Cannot find DMDocument jar file in [some directory]

• This error is reported back to the command line by the lddtool wrapper, which checks for the existence of the DMDocument.jar file before invoking java on it. If you haven't previously set PARENT_DIR in the wrapper to point to the LDDTool installation directory, do so (in some environments this may be required even if you're using the default configuration). If you have already modified PARENT_DIR, search it for typos. The PARENT_DIR directory must contain a lib/ subdirectory, which in turn must contain the DMDocument.jar file.

• You'll also get this message if there is a typo in the lib/ subdirectory name or DMDocument.jar name (case counts).

  >>error - Required data file was not found: [**some path to an XMLfile**]
  

• This will show up as the last line in your listing if you forgot to include the Data/ subdirectory of the LDDTool distribution in your installation LDDTool directory tree. Spelling and case count, so if you're on a linux-based system and accidentally changed “Data” to “data”, for example, you'll get this message.

/bin/java: No such file or directory (This is the linux version of this error)

• Messages like this are reported to the command line and indicate that the JAVA_HOME setting either failed or points to the wrong place. If there's a typo in the JAVA_HOME setting, you might also see characters before "/bin/java" indicating what the script thinks JAVA_HOME was set to. The JAVA_HOME directory must contain a bin/ subdirectory, which in turn must contain the java executable.

« usage info dump »

• If you get a dump of lddtool usage information when you run the test command on the example file, look at the very top - there's probably an error waiting for you. Make sure you spelled the input file name correctly and included the required -lp option set.