Difference between revisions of "Filling Out the DD Class Class"

From The SBN Wiki
Jump to navigation Jump to search
(: Safety Save)
(Update for IM 1.14.0.0)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
''<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.
 
''<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 1.14.0.0 (1E00 schemas)''
 +
 +
  
 
== <name> ==
 
== <name> ==
Line 5: Line 9:
 
''REQUIRED''
 
''REQUIRED''
  
This is the name that will appear in the class tag in your product label. It must be unique within the label.  '''''This is not validated!''''' If the value is not unique, only one of the classes defined with this name will appear in the output schema.
+
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.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''There are a couple of major issues with validation, or rather lack thereof, associated with this ''&lt;name&gt;'' field even when it is unique:''
 +
* ''The character set is not restricted to ASCIIUnless 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.''
 +
|}
  
 
== <version_id> ==
 
== <version_id> ==
Line 11: Line 22:
 
''REQUIRED''
 
''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.
+
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 ''&lt;ldd_version_id&gt;''.
 
 
  
 
== <local_identifier> ==
 
== <local_identifier> ==
Line 18: Line 28:
 
''REQUIRED''
 
''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.  You can use the same value here as you do for ''&lt;name&gt;'' if you like, and the same validation warning applies. Some dictionary writers append a prefix related to the containing class or some other circumstance to help with locating attributes and classes for maintenance.
+
The identifier ''must'' be unique within this dictionary. If you have multiple classes with the same ''&lt;name&gt;'' 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 ''&lt;name&gt;'' 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.  
  
 
== <submitter_name> ==
 
== <submitter_name> ==
Line 24: Line 34:
 
''REQUIRED''
 
''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 ''&lt;full_name&gt;'' value in the ''&lt;Ingest_LDD&gt;'' parameters at the top of the file.
+
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 ''&lt;full_name&gt;'' value in the ''&lt;Ingest_LDD&gt;'' parameters at the top of the file.
  
 
== <definition> ==
 
== <definition> ==
Line 30: Line 40:
 
''REQUIRED''
 
''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.
+
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.
  
 
== <abstract_flag> ==
 
== <abstract_flag> ==
Line 40: Line 50:
 
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.
 
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 this attribute seems to have no effect on the output class definition at all.
+
In fact, when last tested this attribute seemed to have no effect on the output class definition at all.
  
 
== <element_flag> ==
 
== <element_flag> ==
Line 47: Line 57:
  
 
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.
 
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.
 +
 +
{| class="wikitable" style="background-color: lightcyan"
 +
|
 +
'''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 ''&lt;element_flag&gt;'' 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 <code>&lt;element_flag&gt;true&lt;/element_flag&gt;</code> will have an XML element definition created for it in the output dictionary, and can be included directly in the <code>&lt;Mission_Area&gt;</code> of your labels.  All other classes can only appear as subclasses of a class that does have an XML element definition.
 
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 <code>&lt;element_flag&gt;true&lt;/element_flag&gt;</code> will have an XML element definition created for it in the output dictionary, and can be included directly in the <code>&lt;Mission_Area&gt;</code> of your labels.  All other classes can only appear as subclasses of a class that does have an XML element definition.
Line 78: Line 93:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
'''Note: ''' ''This class cannot be used because there are no defined values for the ''&lt;reference_type&gt;'' attribute in this context.  The issue has been reported.''
+
'''Note: ''' ''This class cannot be used because there are no defined values for the ''&lt;reference_type&gt;'' attribute in this context.  The issue has been reported at least twice.''
 
|}
 
|}
  
Line 85: Line 100:
 
''REQUIRED''
 
''REQUIRED''
  
This class associates a ''&lt;DD_Attribute&gt;'' or ''&lt;DD_Class&gt;'' 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.
+
This class associates a ''&lt;DD_Attribute&gt;'' or ''&lt;DD_Class&gt;'' 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 required to be in the same order as the order in which they were mentioned in ''DD_Association'' classes.
+
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 [[Advanced_LDDTool_Techniques#Choice_List|choice list]], but in that case the schema order is not relevant anyway.'')
  
 
=== <identifier_reference> ===
 
=== <identifier_reference> ===
Line 93: Line 108:
 
''REQUIRED''
 
''REQUIRED''
  
The value here should be the ''local_identifier'' value from the ''&lt;DD_Attribute&gt;'' or ''&lt;DD_Class&gt;'' that you want to include in the current class.  It must match exactly.   
+
The value here should be the ''local_identifier'' value from the ''&lt;DD_Attribute&gt;'' or ''&lt;DD_Class&gt;'' that you want to include in the current class.  It must match exactly.  Typically, each ''DD_Association'' will have a single ''&lt;identifier_reference&gt;''.  There is an [[Advanced_LDDTool_Techniques|advanced technique]] for creating a '''choice''' list in your output schema that requires multiple ''&lt;identifier_reference&gt;'' attributes in a single ''DD_Association''.  See the [[Advanced_LDDTool_Techniques]] page for more information.
  
Typically, each ''DD_Association'' will have a single ''&lt;identifier_reference&gt;''There is an [[Advanced_LDDTool_Techniques|advanced technique]] for creating a '''choice''' list in your output schema that requires multiple ''&lt;identifier_reference&gt;'' 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.
  
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.
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''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.''
 +
|}
  
 
=== <reference_type> ===
 
=== <reference_type> ===
Line 103: Line 121:
 
''REQUIRED''
 
''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.
+
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:
 
The valid values are:
Line 126: Line 144:
 
''REQUIRED''
 
''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).
+
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).
 
 
''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> ===
 
=== <maximum_occurrences> ===
Line 144: Line 160:
  
 
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.
 
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.
 +
<!--  **************************************************
 +
      **************************************************
 +
      **************************************************
 +
 +
***  These classes are not properly implemented, thus commented out...
 +
  
 
=== <DD_Attribute_Reference> ===
 
=== <DD_Attribute_Reference> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This class is used to include (by reference) an attribute that is defined in another PDS namespace (that is, someone else's dictionary). This is usually a bad idea, and SBN strongly discourages it except for these specific attributes from the PDS core (pds:) namespace:
 +
 +
::::{|
 +
| align="right" | '''pds:local_identifier'''
 +
| -
 +
| Use this when you want to create a local identifier in your class for referencing elsewhere in the label.  This gets you the character constraints and validation needed for that cross-referencing to work.
 +
|-
 +
| align="right" | '''pds:logical_identifier'''
 +
| -
 +
| Use this when you want to reference a PDS4 LID value outside of a ''&lt;pds:Internal_Reference&gt;'' class. This also gets you the characters constraints and minimal validation needed for that to have a chance to be successful. Note that the PDS ''Validate'' tool will likely ''not'' be able to check referential integrity for these references.
 +
|}
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
| ''This class is undocumented. Aviod it.
+
|  
 +
'''Note:''' ''Use this very cautiously and expect it to break in a subsequent release. There is an unresolved requirements conflict in the underlying design. A problem has been reported.''
 
|}
 
|}
 +
 +
==== <namespace_id> ====
 +
 +
''REQUIRED''
 +
 +
This is not the formal namespace identifier, but rather one of the official namespace prefixes registered in the PDS [https://pds.nasa.gov/datastandards/schema/pds-namespace-registry.pdf Namespace Registry Summary] for the namespace you want to reference. 
 +
 +
==== <name> ====
 +
 +
''REQUIRED''
 +
 +
This is the name of the attribute you wish to reference in that other namespace.  Do no include the namespace prefix (e.g., "pds:") in the value.
  
 
=== <DD_Class_Reference> ===
 
=== <DD_Class_Reference> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
As with ''&lt;DD_Attribute_Reference&gt;'', this class is used to include (by reference) a class that is defined in another PDS namespace (that is, someone else's dictionary). This is usually a bad idea, and SBN strongly discourages it except for these specific attributes from the PDS core (pds:) namespace:
 +
 +
::::{|
 +
| align="right" | '''pds:Internal_Reference'''
 +
| -
 +
| Use this class to formally link your product to another product in the PDS universe.
 +
|-
 +
| align="right" | '''pds:Local_Internal_Reference'''
 +
| -
 +
| Use this class to formally link to something within your label. This class should be recognizable to general-use software and for defining the relationship that exists.
 +
|-
 +
| align="right" | '''pds:External_Reference'''
 +
| -
 +
| Use this class to link to something external to the PDS.  This would not normally appear in local dictionaries - the primary use is for citing the literature from the ''&lt;References&gt;'' class in the label - but if you have a reasonable application for it, it is available.
 +
|}
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
| ''This class is undocumented. Aviod it.
+
|  
 +
'''Note:''' ''Use this very cautiously and expect it to break in a subsequent release. There is an unresolved requirements conflict in the underlying design. A problem has been reported.''
 
|}
 
|}
 +
 +
==== <namespace_id> ====
 +
 +
''REQUIRED''
 +
 +
This is not the formal namespace identifier, but rather one of the official namespace prefixes registered in the PDS [https://pds.nasa.gov/datastandards/schema/pds-namespace-registry.pdf Namespace Registry Summary] for the namespace you want to reference. 
 +
 +
==== <name> ====
 +
 +
''REQUIRED''
 +
 +
This is the name of the class you wish to reference in that other namespace.  Do no include the namespace prefix (e.g., "pds:") in the value.
 +
      **************************************************
 +
      **************************************************
 +
-->

Latest revision as of 19:32, 30 July 2020

<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 1.14.0.0 (1E00 schemas)


<name>

REQUIRED

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.

<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. 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>.

<local_identifier>

REQUIRED

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.

<submitter_name>

REQUIRED

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.

<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. Avoid abbreviations and acronyms that users would not be able to decode without additional documentation.

<abstract_flag>

OPTIONAL

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.

<element_flag>

OPTIONAL

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:

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

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.

<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 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.

<DD_Association>

REQUIRED

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.)

<identifier_reference>

REQUIRED

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.

<reference_type>

REQUIRED

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.

<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 when creating a label. If you want the attribute/sub-class to be optional, then give a value of "0" (zero).

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