Using Local Dictionaries

A local dictionary is any dictionary other than the PDS4 master schema. These include both discipline dictionaries, like the Display Dictionary or the Spectral Dictionary, and mission dictionaries produced by data preparers as part of their archiving process.

Structure of Local Dictionaries

Like the PDS4 master schema, local dictionaries will usually come in two parts: the XML Schema Definition language, or XSD, file, which contains the structural class and attribute information; and the Schematron languade, or SCH, file, which contains standard value lists and attribute relationship requirements. Together, these two files constitute a dictionary that defines a specific and unique namespace. When you wish to use classes from this namespace in your PDS4 label, you will need to reference both of these files.

Where to Find Dictionaries

The officially configured and released dictionaries are available from this website at PDS:

http://pds.nasa.gov/pds4/schema/released/

Development versions should be used with caution, and are available elsewhere on the PDS4 site if desired.

Note: In general, you should not be using mission dictionaries for missions other than the mission you are actually working on/for. If this presents a problem, contact your SBN node consultant.

Schema Files

To use any particular dictionary, you will need to download both the .xsd and the .sch files. If you've set up a local schema archive, you can copy these files into the appropriate place and carry on.

Some software can also reference schema files across an available network connection, so it may not be necessary to have local copies of the files physically present on your system. You will need to know the specific URL, however.

Namespaces

A dictionary, that is, the combination of an .xsd file and its related .sch file, defines all the classes and attributes constituting a unique namespace. The formal name of that namespace will be a URI (Uniform Resource Identifier). For PDS4 namespaces, URIs are in the form of a URL. PDS maintains the dictionary collection at that URL, at least for now (there is no requirement that a URL-like URI be resolvable, but it does make life easier).

Finding the Dictionary Namespace URI

In order to reference the local dictionary in your labels, you will need to know the full, formal namespace URI.

To find the full namespace URI of a local dictionary, open the .xsd file and look at the contents of the <xs:schema> tag near the top of the file. Here, for example, is <xs:schema&gt tag from the version 1.1.0.0 Display Dictionary:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://pds.nasa.gov/pds4/disp/v1"
  xmlns:disp="http://pds.nasa.gov/pds4/disp/v1"
  xmlns:pds="http://pds.nasa.gov/pds4/pds/v1"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  version="1.1.0.0">

The URI of the namespace for any local dictionary is the value of the targetNamespace attribute in this tag. In the example above, we can see that the URI for the Display Dictionary namespace is "http://pds.nasa.gov/pds4/disp/v1".

The Standard Namespace Abbreviation

PDS also strongly prefers that you use standard namespace abbreviations for local dictionaries where abbreviations are called for. You can find the standard abbreviation in the <xs:schema> tag as well. Look for the xmlns: attribute that has the same value as the namespace URI for the dictionary, and the abbreviation will be the part following the colon. So in the example above, the standard abbreviation for the Display Dictionary namespace is "disp".

Setting Up for Validation

If you have set up a local schema tree for referencing via an XML catalog file (see Understanding XML Catalog Files for details), or just so you can remember where they are, you will need to copy both the .xsd and .sch files into the appropriate place for your work environment.

The Tricky Part

Local dictionaries, once developed, tend to remain static. In particular, they are not necessarily updated every time the PDS4 master schema is updated. This is good in terms of keeping your label references current, but it does have a downside for validation. The local dictionaries will likely be referencing older versions of the PDS4 master schema. Local dictionaries reference the master schema data type list and unit classes, which are very stable, so there is little reason to worry about updating schema references.

But, if you want to be able to do full validation with your schema-aware editor, then you may have validation issues with the local dictionaries if you don't download the older versions of the master schema that they depend on. To see which version of the PDS4 master schema is being referenced, look for the <xs:import> statement near the top of the label. Here is the <xs:import> statement from the Display Dictionary:

  <xs:import namespace="http://pds.nasa.gov/pds4/pds/v1"
    schemaLocation="http://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1101.xsd"/>

The version number of the master schema is part of this file name referenced in the schemaLocation attribute (here given as a URL reference). The PDS4 master schema version referenced here is "1.1.0.1". So to complete the validation chain you will need to download the .xsd and .sch files for this older version of the master schema, and install them in your local environment as well.

This is where a local schema library and XML Catalog file can make your validation life much easier. See Understanding XML Catalog Files for more information.