Filling Out the DD Class Class

From The SBN Wiki
Jump to navigation Jump to search

<DD_Class> is used to define a group of related attributes and, possibly, sub-classes. Repeat it once for each class you want to define.

Last Update: 29 July 2020, for IM (1E00 schemas)



This is the name that will appear in the class tag in your product label. In most dictionaries, class names should be unique. If you have a complex case, where you need special validation constraints that cannot be accommodated through simple Schematron rules and minimum/maximum occurrence constraints, then you want to - very carefully - duplicate class names. Talk with your PDS consultant about this first, though, and make sure your dictionary documentation makes the intent of this duplication clear to dictionary reviewers.

There are a couple of major issues with validation, or rather lack thereof, associated with this <name> field even when it is unique:

  • The character set is not restricted to ASCII. Unless you know the environment you're working in is configured to treat UTF-8 properly and you know how to get the proper code points into your Ingest_LDD file for UTF-8 characters, you should avoid UTF-8. You should probably avoid it anyway for this field.
  • The character set is not restricted to letters, numbers, and underscores, or in fact even to printable characters. A fair number of those currently permitted characters are problematic for processing and should be aggressively avoided. Character entity substitutions are not a viable alternative here.



This is a version specific to this DD_Class definition. Use it to track progress on specific class definitions independently of the dictionary as a whole. This is required to have the format M.n. SBN strongly recommends you increment the major version number when you make a non-backwards compatible change to your class definition, and propagate that change to your dictionary <ldd_version_id>.



The identifier must be unique within this dictionary. If you have multiple classes with the same <name> value, this is the identifier that distinguishes between them. This is the ID you will use to include this class as a sub-class of other classes. You can use the same value here as you do for <name> if you like (and if it is unique). Some dictionary writers append a prefix related to the containing class or some other circumstance to help with locating attributes and classes for maintenance.



This is the name of the person responsible for this particular class definition. In large projects, dictionary development duties may be delegated to several individuals, and this field enables tracking that responsibility. In small projects, this will be the same as (or equivalent to) the <full_name> value in the <Ingest_LDD> parameters at the top of the file.



This should be a short, human-readable explanation of the class contents, or why it exists. This will be reviewed in the peer review and available to posterity. Avoid abbreviations and acronyms that users would not be able to decode without additional documentation.



Do not use this attribute.

If this attribute has a value of true, it is supposed to indicate that this class cannot itself be used in labels, but rather is used as a parent class for deriving other classes in other dictionaries. This would be a fairly advanced technique that most local dictionary preparers would never need to employ.

In fact, when last tested this attribute seemed to have no effect on the output class definition at all.



A value of true indicates that this class should be defined as an XML element (as opposed to an XML type) in the output XSD schema. You should include this attribute with a value of true for the top-level classes you plan to include in your labels. If you give a value of false, or do not include this attribute in the DD_Class, then the class will only be defined as an XML type.

Note: At least one class must have this element set to true or no user will be able to use anything in your dictionary. The 1E00 version of LDDTool should report an error if it finds no classes with <element_flag> set to true.

Here's what's going on: For various reasons based on modelling, inheritance, and validation requirements, PDS dictionary schemas define classes and attributes as XML types, and create XML elements only at the highest levels. This ensures uniformity of definition and tag names down through the entire structure. When you create your Ingest_LDD input file, you should consider how you want to include your local classes in your labels. Any class you define with <element_flag>true</element_flag> will have an XML element definition created for it in the output dictionary, and can be included directly in the <Mission_Area> of your labels. All other classes can only appear as subclasses of a class that does have an XML element definition.

By default, none of the classes defined in your Ingest_LDD will have XML element definitions in the output, so you will have to use this attribute in at least one of your classes. As a quick example, say you've defined a structure like this:


In order to include the entire ClassA in the label, you must set element_flag in the ClassA DD_Class definition to true. Setting element_flag to true when defining ClassD, however, would make it possible to include <ClassD> directly in your label without the wrapper classes that contain it.

Valid values are true and false.



As for <DD_Attribute>, if you have a class that would be much more understandable in conjunction with an explanatory graphic or supplementary document, you can use this to associate that product with this class definition. Use the same sort of criteria here as for the <DD_Attribute>/<Internal_Reference>, above.

Note: This class cannot be used because there are no defined values for the <reference_type> attribute in this context. The issue has been reported at least twice.



This class associates a <DD_Attribute> or <DD_Class> definition with this class and defines the parameters of that association. You may not define recursive or circular associations, either directly or indirectly. Trying to do so, accidentally or otherwise, can lead to some very random error messages.

Repeat this class once for every attribute or sub-class you want to include as part of this class. In the output XSD schema file, the attributes and sub-classes will be in the same order as the order in which they were listed in DD_Association classes. (Note: This is not true if your class is a choice list, but in that case the schema order is not relevant anyway.)



The value here should be the local_identifier value from the <DD_Attribute> or <DD_Class> that you want to include in the current class. It must match exactly. Typically, each DD_Association will have a single <identifier_reference>. There is an advanced technique for creating a choice list in your output schema that requires multiple <identifier_reference> attributes in a single DD_Association. See the Advanced_LDDTool_Techniques page for more information.

Similarly, if you want to reference a type, attribute, or class from another namespace, there is a syntactical trick to do this available. But you should only do this if you have seriously good reasons to do so. You can find the details for this on the Advanced_LDDTool_Techniques page.

Note: This attribute is not currently validated as a reference - that is, if your reference is not pointing to anything, you will get no error or warning. Type carefully.



This string describes the relationship between the class you're defining and the attribute(s) or sub-class(es) identified by the local_identifier value(s) immediately preceding.

The valid values are:

attribute_of - The local_identifier references an attribute to be included in this class.
component_of - The local_identifier references a class to be included as a sub-class in this class.
parent_of - This class is a parent class from which the class identified by local_reference is derived.

The parent_of value is used in conjunction with some advanced dictionary-creation features. Contact your PDS node consultant if you're planning on using this and related constructs.



This attribute provides the minimum number of times the referenced attribute or sub-class is required to be included in the current class when creating a label. If you want the attribute/sub-class to be optional, then give a value of "0" (zero).



This attribute provides the maximum number or times the referenced attribute or sub-class may be included in the current class. If you want the attribute/sub-class to appear in labels a specific number of times, then <minimum_occurrences> and <maximum_pccurences> should have the same value.

If you do not want to limit the number of times the attribute/sub-class can be repeated, use a value of "unbounded":




If you want to require that a particular attribute contains a specific, fixed value whenever it occurs in this class, you can assign it a constant value using this parameter. You might want to do this, for example, if you have classes that include the same keyword, but that keyword value is not variable in some classes.