Getting Started

Background

The PDS4 Information Model, PDS4 Data Dictionary, and their XML representation in the PDS4 Common Schema and Schematron serve as a library of generic definitions for each PDS4 product type. PDS also maintains data dictionaries for specialized disciplines such as geometry and cartography and for specific planetary missions; these are called Local Data Dictionaries or LDDs. They are also expressed as XML schemas for use in PDS labels. The PDS4 Schema and all current Local Data Dictionary schemas are available at https://pds.nasa.gov/datastandards/schema/released/.

When a schema is used in a PDS4 label it is associated with a namespace. A namespace is a context for the terms defined in the schema. The common PDS4 schema has the namespace pds, and it is the default namespace in a PDS4 label. Other namespaces correspond to Local Data Dictionaries such as cart for the Cartography Dictionary, disp for the Display Dictionary, and mvn for the MAVEN Mission Dictionary If classes or attributes from other namespaces are used in the label, the terms are prefixed with that namespace, as in cart:map_projection_name and disp:vertical_display_direction. Only namespaces that are registered in the Namespace Registry may be used in PDS4 labels. To request a new namespace, see instructions here.

When you prepare data for delivery to PDS, you will certainly be involved in creating labels; you may also be involved in creating discipline- or mission-specific LDDs. This section will focus on the components of labels, design choices you will need to make, and tools you can use. Basic information about XML and XML schemas can be found in Appendix C, specific instructions for editing PDS XML labels are in Appendix D, and a discussion about creating Local Data Dictionaries is available on the Small Bodies Node PDS4 Wiki (https://sbnwiki.astro.umd.edu).

For more details, see the PDS4 Data Provider’s Handbook (DPH), PDS4 Standards Reference (SR), and of the other PDS4 Standards Documentation.

Additional PDS4 Documentation

Here are some additional websites that may help provide more details about NASA Planetary Data System (PDS), our international partners at the International Planetary Data Alliance (IPDA), and the PDS4 Data Standard:

Getting to Know Your LDD Repo

Overview

Assuming a new LDD Github Repo has been generated for you, this section and its subsections will describe the directories, associated files, and and the automated dictionary generation and validate performed automatically by the repo through Github Actions.

The default directory structure and file locations are very important to ensuring the continuous integration built into the repository executes successfully.

LDD Generation and Validation

Each LDD Github repo generated from the ldd-template repo will contain Github Actions to do the following:

Generating schemas and schematrons

The github action will download and run the latest LDDTool and generate the schemas and schematrons from your Ingest LDD using the expected LDDTool flags.

What does this mean?

The schemas and schematrons in your repository should always be generated using the latest LDDTool and using the configuration that an operational release would expect. It really helps ensure all LDDs are generated the same way and include the same set of files.

Additionally,*you should NOT generate and push schemas or schematrons to your repository manually*. To minimize inconsistencies across LDDs, all schemas and schematrons posted on Github should be auto-generated by Github, or generated and pushed by EN Operations staff.

What does this NOT mean?

This does not mean you shouldn’t download LDDTool and test locally. Github Actions are great, but can be kind of slow generating the schemas, so I would recommend running LDDTool locally to test before pushing an update to Github per the LDD Update Process.

LDD Validation

The github action also downloads Validate Tool, performs basic validation of your schemas and schematrons, and performs regression testing against any tests in the test/ directory of your repo. See :doc:LDD Regression Testing for more info on how to populate the test directory.

Repo Directory Structure

Warning

Please do not remove or move the directories unless told it is OK by the descriptions of the directories below.

Below is an example of the default repo layout for the cart namespace. This is an example and the exact layout of the generated repo is subject to change, but the following subsections of this guide will be updated as needed. For the latest layout checkout the ldd-template repo:

├── README.md
├── pds4_versions.txt
├── build
│   └── development
│   └── release
├── src
│   ├── PDS4_EXAMPLE_IngestLDD.xml
│   └── dependencies
├── test
│   ├── No.Data
│   ├── test1_FAIL.xml
│   └── test1_VALID.xml

README.md

  • Update the Contribute section of your new repos README.md with an appropriate description and steward contact information.

For more general information on READMEs, see Github documentation.

pds4_versions.txt

This text file contains the applicable PDS4 Versions to build against for LDDs in your repo. Feel free to remove versions that are not applicable or add new versions by adding a newline and the applicable version number. Note: The Github CI/CD only works for PDS4 IM versions 1.11.0.0 and later.

build/

This directory is where all the schemas, schematrons and other files generated from LDDTool are placed.

  • development - this directory will contain the current development version of the schema. You should always be able to direct someone here if they want to be able to test with the schemas that are currently in development for next build.

** release - this directory will contain all released versions of the LDD from PDS4 Stadard Version 1.15.0.0 and later. This directory is maintained for configuration management only. Users should be directed to download from the archival, released version at pds.nasa.gov.

src/

This directory is where the IngestLDD and it’s associated dependencies are located.

  • IngestLDD.xml - this file must be located in this directory in order for the continuous integration to work properly. The file name must also (1) contain IngestLDD and (2) have a file suffix of .xml.

  • dependencies/ - in the event that your Discipline Dictionary inherits classes from another Discipline Dictionary, this directory will use Github submodules to link to the other repository. If that does not apply to your dictionary, you can remove this directory. If it does, contact the PDS Steward Admins to get help setting this up.

test/

See LDD Regression Testing for more details.

Trying It Out

Before trying it out on your own repository, I recommend reviewing the LDD Update Process and completing the LDD Update and Build Tutorial

Handling LDD dependencies

If your Discipline LDD has a dependency on another Discipline LDD, you will need to complete the following changes to your repository after it has been created:

  1. Create a new src/dependencies directory:

    mkdir -p src/dependencies

  2. Create a submodule to the LDD is in the dependent repo:

    cd src/dependencies
git submodule add https://github.com/pds-data-dictionaries/ldd-geom

  3. You should now see a src/dependencies/ldd_geom directory:

    $ ls
README.md
ldd-geom/

  4. Commit and push your changes to a branch and merge.