Filling Out the DD Class Class

From The SBN Wiki
Revision as of 14:03, 27 March 2015 by Raugh (talk | contribs) ()
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.

<name>

REQUIRED

This is the name that will appear in the class tag in your product label. It does not have to be unique in the dictionary - you can define a class name more than once if you want to use the same class (with different constraints, for example) as a sub-class in more than one other class. Do this with caution; the potential for confusion is significant.

<version_id>

REQUIRED

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. There are no specific format requirement on this version number, and it is not required to have any specific relationship to the dictionary version_id. On other words, you have a fair amount of freedom to define a versioning system appropriate to your development environment and circumstances.


<local_identifier>

REQUIRED

The identifier must be unique within this dictionary. This is the ID you will use to include this class as a sub-class of other classes, and this is why you can have two or more classes with the same <name> but different definitions - the unique <local_identifier> distinguishes them.

<submitter_name>

REQUIRED

This is the name of the person responsible for this particular classdefinition. 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.

<definition>

REQUIRED

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.

<abstract_flag>

OPTIONAL

If this flag has a value of true, it indicates that this class cannot itself be used in labels, but rather is used as a parent class for deriving other classes. This is a fairly advanced technique that most local dictionary preparers will not need to employ. If it sounds like something you'd find useful, ask your PDS node consultant for additional information and examples.

Valid values are true and false.

<element_flag>

OPTIONAL

A value of true indicates that this class should be defined as an element in the output XSD schema file, rather than just as a type. Typically, this can be omitted, but if you want the gory details, read on.

By default, only the highest-level classes defined in your Ingest_LDD - those not associated with other classes - will appear in the output XSD schema file as something that can be included in your labels. So if you've defined a structure like this:

   <ClassA>
       <attribute1>
       <attribute2>
       <ClassB>
           <ClassD>
           </ClassD>
           <ClassE>
           </ClassE>
       </ClassB>
   </ClassA>

You would have to include the entire ClassA in the label if you wanted to provide values for ClassD. 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.

<Internal_Reference>

OPTIONAL

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 the product with this class definition. Use the same sort of criteria here as for the <DD_Attribute>/<Internal_Reference>, above.

<DD_Association>

REQUIRED (but see description)

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.

<local_identifier>

REQUIRED

This is 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 <local_identifier>. There is an advanced technique for creating a choice list in your output schema that requires multiple <local_identifier> attributes in a single DD_Association. See the Advanced_LDDTool_Techniques page for more information.

<reference_type>

REQUIRED

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

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.

<minimum_occurrences>

REQUIRED

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

Note: If you included a series of, for example, attribute local_identifiers in the DD_Association, and have a value of minimum_occurrences that is greater than one, bear in mind that in the label the first attribute will must be repeated minimum_occurrences times, then the second attribute will be repeated, and so one. This does not create a repeating group.

<maximum_occurrences>

REQUIRED

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":

       <maximum_occurrences>unbounded</maximum_occurrences>

<constant_value>

OPTIONAL

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 is value is not variable in some classes.

<DD_Attribute_Reference>

OPTIONAL

This class is undocumented. Avoid it.

<DD_Class_Reference>

OPTIONAL

This class is undocumented. Avoid it.