sbn-psi / ldd_utilities

Miscellaneous utilities for working with local data dictionaries in PDS4

ldd_utilities

Miscellaneous utilities for working with local data dictionaries in PDS4

IngestLddView

The first utility is IngestLddView, which will convert an Ingest LDD file into files that are easier for a non-XML user to use and visualize.

Requirements

You will need an XML stylesheet processor such xsltproc or saxon to transform your dictionary.

xsltproc is available at http://xmlsoft.org/XSLT/xsltproc2.html

Saxon is available at https://sourceforge.net/projects/saxon/files/Saxon-HE/9.8/

If you want to be able to visualize the dictionary, you will need Graphviz, which is available at https://www.graphviz.org/

Mitch Gordon at SETI has provided some additional notes on using IngestLDDView with windows.

Getting the stylesheets

You can download both stylesheets from GitHub. Unless you have GitHub experience, use the links below:

HTML version

Graphviz Version

Html

IngestLddView will convert an Ingest LDD file into a (more) human-readable html document.

This will include every class in the dictionary, starting from any class that has the element flag. From there, it will show nested classes and attributes. If the namespace prefix is correct, it will also show the XPath expression for each element, and the human readable description of the schematron rules for that element.

IngestLddView can be invoked with the following command

xsltproc IngestLddView.xsl [ingest ldd file] > [htmlfile]

or

saxon -xsl:IngestLddView.xsl -s:[ingest ldd file] -o:[htmlfile]

Graphviz

A graphviz companion to IngestLddView is IngestLddDot. This will convert an Ingest LDD file into a graphviz dot file, which can be used to quickly visualize the relationships between classes, as well as find problems such as orphaned classes, attributes or rules. IngestLDDDot is invoked the same way as IngestLDDView:

xsltproc IngestLddDot.xsl [ingest ldd file] > [dotfile]

or

saxon -xsl:IngestLddDot.xsl -s:[ingest ldd file] -o:[dotfile]

From there, your dot file can be converted to a graphical format.

For instance, to get a pdf, run:

dot -O -Tpdf [dotfile]

UML

A UML companion to IngestLddView is IngestLddDot. This will convert an Ingest LDD file into a PlantUML file, which can be used to quickly visualize the relationships between classes. IngestLDDPlantUML is invoked the same way as IngestLDDView:

xsltproc IngestLddPlantUml.xsl [ingest ldd file] > [umlfile]

or

saxon -xsl:IngestLddPlantUml.xsl -s:[ingest ldd file] -o:[umlfile]

From there, your uml file can be converted to a graphical format.

For instance, to get an svg, run:

plantuml -tsvg [uml]

Known issues:

Need to add support for xs:any The output is not exactly attractive. Need to format it for easier comprehension.

ldd_utilities's Issues

IngestLddView.xsl should preserve the formatting of /Ingest_LDD/comment

Hi there,

Many thanks for making this tool available. I'm not using this for our own LDDs, but rather to make discipline dictionaries (e.g. msn) easier to browse when looking for suitable PDS4 matches for our data structures.

Anyway, I've noticed that the text contained in the /Ingest_LDD/comment element is wrapped in a <p> tag in the generated HTMLs. As most of the dictionaries I've processed seem to use the comment element to keep both a general description and full change log, the result tends to be a rather unwieldy blob of text where all formatting is lost.

What I've done as a workaround is to simply exchange the <p> for a <pre> tag, which serves to preserve the original formatting. Would you consider adopting this workaround for IngestLddView.xsl itself, or are there other concerns that I am missing?

Cheers,
Ariel

IngestLDDView Cardinality

This could be a very handy tool for reviewers inspecting mission dictionaries, as well as providing an alternate form of documentation for any dictionary. With that in mind, the cardinality notation ("(1-1)", "(0-1)", etc.), might be a little too obscure for our reviewers or new users. Is it possible to replace it with human-readable text like "optional" or "required" (if the first number is '0' or anything other than '0', respectively), and an indication of repeatability? Gets a little tricky, since it's possible to be required a specific number of times, repeatable up to some maximum number; or repeatable as desired. So values like:

• Required (rather than "1-1")
• Optional (rather than "0-1")
• Required 2 times (rather than "2-2")
• Optional, Repeatable (rather than "0-*")
• Required, Repeatable to 4 times (rather than "1-4")
• etc.

Easier and probably sufficient would be to put some explanatory text at the top of the page defining the notation.