Difference between revisions of "Advanced LDDTool Techniques"

From The SBN Wiki
Jump to navigation Jump to search
m
(Creation - Safety Save)
Line 31: Line 31:
 
* A ''<code>choice</code>'' list defined in this way may contain only one kind of referenced object - either all attributes or all classes, but not both in the same ''DD_Association''.
 
* A ''<code>choice</code>'' list defined in this way may contain only one kind of referenced object - either all attributes or all classes, but not both in the same ''DD_Association''.
 
* The ''&lt;minimum_occurrences&gt;'' and ''&lt;maximum_occurrences&gt;'' values you provide for this ''DD_Association'' refer to the total number of selections that may be made by a label writer from the list of things corresponding to the ''local_identifier'' values.
 
* The ''&lt;minimum_occurrences&gt;'' and ''&lt;maximum_occurrences&gt;'' values you provide for this ''DD_Association'' refer to the total number of selections that may be made by a label writer from the list of things corresponding to the ''local_identifier'' values.
 +
 +
 +
== ''Any'' Block ==
 +
 +
''Any'' blocks are used within the shared PDS4 namespaces to pass validation control from one dictionary to another within a defined class.
 +
 +
=== What Is It? ===
 +
 +
The XSD ''<code>any</code>'' construct specifies that from this point until the closing tag of the current XML element, any elements from any namespace may be included and will not be subject to validation by the rules defined for the current namespace (they are required to be syntactically valid XML). 
 +
 +
''(Actually, you can also include elements from the current namespace, and they will be subject to validation as though they had occurred in their usual place in their label.  This, however, is an excellent way to generate almost completely intractable error messages, and should be avoided.)''
 +
 +
 +
=== How Do I Do It? ===
 +
 +
As the last association in your ''&lt;DD_Class&gt;'' (yes, it absolutely '''''must''''' be the "last" association, since anything after an ''<code>any</code>'' statement in the schema is ignored), add one more ''&ltDD_Association&gt;'' class with a ''&lt;local_identifier&gt;'' value of "<code>XSAny#</code>".  The remaining attributes of ''DD_Class'' must be there, but will be ignored.
 +
 +
'''Note''' that:
 +
* If a schema validator can identify what namespaces the elements in the ''<code>any</code>'' area come from, and has a schema to validate them against, it will do so and report errors accordingly.  So if you plan to include ''<code>any</code>'' blocks in your local dictionary classes, you should expect that your PDS standards reviewers will require that they only reference attributes and classes from namespaces for which PDS administers the defining schema.
 +
* Using the ''<code>any</code>'' construct abdicates control of both content and validation for that part of your mission labels. If you do not have direct and significant influence over what might be thrown into this unregulated label area, you really shouldn't be leaving this particular barn door open.

Revision as of 13:36, 30 March 2015

There are some advanced techniques available via the <Ingest_LDD> document and the LDDTool that might be useful in some complex cases. On the whole, SBN recommends that you resort to these only when there are compelling reasons to do so. These features are the more experimental, and thus more unstable, parts of the package.

Schematron Rules

Schematron rules can be used to check the sort of contingency relationships (i.e., "If A, then B") that XML Schema is not particularly good at. PDS also uses Schematron to define enumerated value lists rather than XML Schema largely for the diagnostic benefits - we can include the list of valid values in the Schematron error message.

Schematron rules are applied to an XML document via a two-step process involving style sheet translations (XSL). There are some subtleties to how and when Schematron rules are triggered, so if you're going to start writing Schematron rules yourself you should take some time to become familiar with the details of the standard. There are also multiple forms of the standard with a couple of significant differences in capabilities for the more advanced Schematron programmer. PDS requires ISO Schematron, which is available as a "Publicly Available Standard" (i.e., free if you promise to behave yourself) from this ISO website: http://standards.iso.org/ittf/PubliclyAvailableStandards. Search for "Schematron".

A limited capability to define additional Schematron rules as part of LDDTool processing is provided via the <DD_Rule> class. DD_Rule classes may be added after the <DD_Class> definitions in your <Ingest_LDD> document. Details for filling out the class are on the Filling Out the DD_Rule Class page.

Choice List

The XML Schema Definitions (XSD) language is very strictly ordered, but it does provide one exception to this rule: the choice construct.

What Is It?

Choice is a mechanism that allows your label writers to use one or more of a list of attributes or subclasses at a particular point in a local class structure. In those cases where more than one list item may be included, the items may occur in any order, and may themselves be repeated. In other words, if I define a choice list containing A, B, and C, and allow label writers to select up to three of these to include, they can include B three times, or C then A and then C again, and either case would be considered equally valid (along with all the other permutations, of course).

So, on the one hand the choice construct defeats some of the validation we get from using XSD, but on the other hand sometimes you can't practically code all the explicit contingencies you might have in certain scenarios.

On the whole, you should usually have some compelling reasons to resort to a choice construct in a local dictionary because of the impact on validation. "I keep getting errors from having my attributes out of order" is not a "compelling reason".

How Do I Do It?

The basic technique is to use a single <DD_Association> class to list all the possible attributes or subclasses that may be included at that point in the containing class being defined. Within that single DD_Association:

  • Repeat the <local_identifier> tag for each attribute or class you want to include in the choice list.
  • Somewhere in that list of local_identifiers, add this:
<local_identifier>XSChoice#</local_identifier>

Note that:

  • A choice list defined in this way may contain only one kind of referenced object - either all attributes or all classes, but not both in the same DD_Association.
  • The <minimum_occurrences> and <maximum_occurrences> values you provide for this DD_Association refer to the total number of selections that may be made by a label writer from the list of things corresponding to the local_identifier values.


Any Block

Any blocks are used within the shared PDS4 namespaces to pass validation control from one dictionary to another within a defined class.

What Is It?

The XSD any construct specifies that from this point until the closing tag of the current XML element, any elements from any namespace may be included and will not be subject to validation by the rules defined for the current namespace (they are required to be syntactically valid XML).

(Actually, you can also include elements from the current namespace, and they will be subject to validation as though they had occurred in their usual place in their label. This, however, is an excellent way to generate almost completely intractable error messages, and should be avoided.)


How Do I Do It?

As the last association in your <DD_Class> (yes, it absolutely must be the "last" association, since anything after an any statement in the schema is ignored), add one more &ltDD_Association> class with a <local_identifier> value of "XSAny#". The remaining attributes of DD_Class must be there, but will be ignored.

Note that:

  • If a schema validator can identify what namespaces the elements in the any area come from, and has a schema to validate them against, it will do so and report errors accordingly. So if you plan to include any blocks in your local dictionary classes, you should expect that your PDS standards reviewers will require that they only reference attributes and classes from namespaces for which PDS administers the defining schema.
  • Using the any construct abdicates control of both content and validation for that part of your mission labels. If you do not have direct and significant influence over what might be thrown into this unregulated label area, you really shouldn't be leaving this particular barn door open.