Filling Out the DD Rule Class

From The SBN Wiki
Revision as of 15:33, 22 January 2017 by Raugh (talk | contribs) ()
Jump to navigation Jump to search

The ability to define Schematron rules gives you another mechanism for validating labels through defined dependencies and contingencies over and above what the XSD Schema standard provides. For example, you can define a rule that requires that any label that contains ClassA also contains ClassB, or that all calibrated products contain a class with instrument calibration parameters.

Each <DD_Rule> class defines one Schematron <rule> definition. The Schematron <pattern> blocks are generated as needed by LDDTool.

You should have an understanding of how to write XPath specifications and Schematron statements before diving in here, or the terminology can be rather opaque. There is much more flexibility in Schematron itself than there is in these classes, and you should use them very carefully as this is an area of active Ingest_LDD/LDDTool development. Keep your rules very simple and very explicit, and you should be OK.

Note: There are additional subclasses defined in the PDS4 schema for this class, but these are left-over from early prototyping efforts and are ignored by the process that analyzes this class content and produces the Schematron rules in the output. They will be removed in later releases and thus are not documented here.

<local_identifier>

REQUIRED

This value provides a handle for this rule within the dictionary. It must be unique within the Ingest_LDD file.

<rule_context>

REQUIRED

The value of this attribute is the Xpath path defining the context for the rule. Specifically, it provides the value of the context XML attribute of the Schematron <rule> element.

N.B.: references to elements defined in this local dictionary must be prepended with the namespace abbreviation defined in the <namespace_id> at the top of the Ingest_LDD class using the standard colon (':') separator.

<rule_assign>

OPTIONAL

This attribute is related to adding a Schematron variable definition capability (a <let> defined inside the <rule>. This capability is not yet available. Do not use this attribute.

<DD_Rule_Statement>

REQUIRED

This class defines the various bits and pieces that go into a single <assert> or<report> element. If the corresponding <rule> element does not already exist, it will be created.

<rule_type>

REQUIRED

This value indicates the type of test to be defined. There are only two defined values you should ever use:

Assert - Creates an <assert> element within the <rule>.
Report - Creates a <report> element within the <rule>

An assert statement does nothing if the associated <rule_test> is true. If the test is not true, the <rule_message> is displayed. A report statement does the opposite - it displays the <rule_message> text only if the <rule_test> is true.

<rule_test>

REQUIRED

This attribute contains the text that will go into the test XML attribute of the <assert> or <report> element being defined. Make sure that you use the local dictionary namespace abbreviation in all references to elements from this dictionary. Referencing any other namespace is currently highly problematic and should be avoided.

The test string must, of course, use the appropriate Schematron test syntax.

<rule_message>

REQUIRED

This attribute provides the message that will be displayed when the associated assert or report is triggered.

<rule_description>

OPTIONAL

Use this free-text field to provide a human-readable explanation of what is being tested and why, if it is not already clear from the rule_message text. This appears to be entirely internal documentation - the description is not transferred to the output Schematron file produced by LDDTool.

<rule_value>

OPTIONAL

This attribute is deprecated. Do not use it.