These properties are for array elements (XSD maxOccurs >1 or unbounded) or optional elements (XSD minOccurs 0 and XSD maxOccurs 1). The properties handle a logical one-dimensional array of any simple or complex type.
| Property Name | Description |
|---|---|
| occursCountKind |
Enum Specifies how the actual number of occurrences is to be established. Valid values 'fixed', 'expression', 'parsed', 'implicit' ,'stopValue'. 'fixed' means use the XSD maxOccurs property. 'expression' means use the dfdl:occursCount property. 'parsed' means that the number of occurrences is determined solely by speculative parsing. 'implicit' means that the number of occurrences is determined by speculative parsing in conjunction with the XSD minOccurs and XSD maxOccurs properties. 'stopValue' means look for a mandatory logical stop value which signifies the end of the occurrences. These values are described in detail in section 16.1. Annotation: dfdl:element |
| occursCount |
DFDL Expression Specifies the number of occurrences of the element. Required only when dfdl:occursCountKind is 'expression'. This property is computed by way of an expression which returns a non-negative integer. The expression must not contain forward references to elements which have not yet been processed. Annotation: dfdl:element, |
| occursStopValue |
List of DFDL Logical Values A whitespace separated list of logical values that specify the alternative logical stop values for the element. Required only when dfdl:occursCountKind is 'stopValue'. When parsing then if an occurrence of the element has a logical value that matches one of the values in this list then the parser MUST not expect any more occurrences of the element. On unparsing the first value will be inserted as an additional final occurrence in the array after all the occurrences in the Infoset have been output. The dfdl:occursStopValue property must not be empty string. Annotation: dfdl:element |
Table 52 Properties for Array Elements and Optional Elements
When XSD minOccurs 1 and XSD maxOccurs 1, the above properties are not used, and the behavior is as if dfdl:occursCountKind was 'fixed' as described in section 16.1.1.
The enum 'fixed' should be used when the number of occurrences is always the same. The number is provided by the XSD maxOccurs property.
When parsing, maxOccurs occurrences are expected in the data. It is a processing error if less than maxOccurs occurrences are found or defaulted. The parser stops looking for occurrences when maxOccurs have been found or defaulted. When maxOccurs is 0, no occurrences are looked for in the data.
When unparsing, maxOccurs occurrences are expected in the Infoset. It is a processing error if less than maxOccurs occurrences are found or defaulted. The processor stops looking for more occurrence in the Infoset after maxOccurs occurrences have been found. When maxOccurs is 0, no occurrences are looked for in the Infoset or written.
It is a Schema Definition Error if XSD minOccurs is not equal to XSD maxOccurs.
The enum 'implicit' should be used when the number of occurrences is to be established using speculative parsing, and there are lower and upper bounds to control the speculation. The bounds are provided by the XSD minOccurs and XSD maxOccurs properties.
When parsing, up to maxOccurs occurrences are expected in the data. It is a processing error if less than XSD minOccurs occurrences are found or defaulted. The parser stops looking for occurrences when either XSD minOccurs have been found or defaulted and speculative parsing does not find another occurrence, or XSD maxOccurs have been found or defaulted. When XSD maxOccurs is 0, no occurrences are looked for in the data.
When unparsing, up to XSD maxOccurs occurrences are expected in the Infoset. It is a processing error if less than XSD minOccurs occurrences are found or defaulted. The processor stops looking for more occurrences in the Infoset after XSD maxOccurs occurrences have been found. When XSD maxOccurs is 0, no occurrences are looked for in the Infoset or written.
The enum 'parsed' should be used when the number of occurrences is to be established solely using speculative parsing.
When parsing, any number of occurrences is expected in the data. The parser stops looking for occurrences when speculative parsing does not find another occurrence. If validation is enabled, it is a validation error if less than XSD minOccurs occurrences are found or defaulted, or greater than XSD maxOccurs occurrences are found.
When unparsing, any number of occurrences is expected in the Infoset. If validation is enabled, it is a validation error if less than XSD minOccurs occurrences are found or defaulted, or if more than XSD maxOccurs occurrences are found.
The enum 'expression' should be used when the number of occurrences is calculated by evaluating a DFDL expression.
When parsing, the dfdl:occursCount expression is evaluated and provides the number of occurrences expected in the data. It is a processing error if less than dfdl:occursCount occurrences are found or defaulted. The parser stops looking for occurrences when dfdl:occursCount occurrences have been found. If validation is enabled, it is a validation error if less than XSD minOccurs occurrences are found or defaulted, or more than XSD maxOccurs occurrences are found. When dfdl:occursCount is 0, no occurrences are looked for in the data.
When unparsing, any number of occurrences are expected in the Infoset. If validation is enabled, it is a validation error if less than XSD minOccurs occurrences are found or defaulted, or if more than XSD maxOccurs occurrences are found. The dfdl:occurs expression is not evaluated. The ‘count’ is the number of occurrences in the augmented Infoset.
It is a Schema Definition Error if dfdl:occursCount is not provided or in scope.
The enum 'stopValue' should be used when the end of the array is signaled by an occurrence having a logical value that is equal to one of the specified 'stop values'.
When parsing, any number of occurrences is expected in the data, followed by an occurrence which is a stop value as specified by dfdl:occursStopValue. It is a processing error if a stop value occurrence is not found in the data (including when there are zero other occurrences). The parser stops looking for occurrences once a stop value has been found. If validation is enabled, it is a validation error if less than XSD minOccurs occurrences are found or defaulted, or more than XSD maxOccurs occurrences are found, not including the stop value.
When unparsing, the behavior is the same as for 'parsed', with the addition that a stop value occurrence is output after the last Infoset occurrence. If dfdl:occursStopValue provides multiple stop values then the first is used.
The stop value itself is not added to the Infoset when parsing. It is a processing error if a stop value is found in the Infoset when unparsing. (This ensures that the array can be reparsed, as the stop value will be placed automatically and only at the end.)
It is a Schema Definition Error if dfdl:occursStopValue is not provided or in scope.
It is a Schema Definition Error if the type of the element is complex.
It is a Schema Definition Error if any of the stop values provided by dfdl:occursStopValue do not conform to the simple type of the element.
When parsing, required occurrences that have empty representation may trigger the application of a default value, as described in Section 9.5.2 Element Defaults When Parsing.
When unparsing, required occurrences that are missing from the Infoset may trigger the application of a default value, as described in Section 9.5.3 Element Defaults When Unparsing.
The application of default values is not dependent on dfdl:occursCountKind, only on whether the occurrence is required or optional, whether there is a default value specified, and whether the data contains the empty representation (parsing) or is missing (unparsing). Section 9.5 Element Defaults contains the details.
If the value of a DFDL property of an array element (other than dfdl:occursCount) is given by a DFDL Expression, then the expression MUST be re-evaluated for each occurrence of the element in case the value changes.
Arrays can have points of uncertainty depending on the value of dfdl:occursCountKind. See Section 9.4.3 Points of Uncertainty for details.
In some situations, arrays of elements and sequence groups of elements seem to be similar; however, there is no notion of the array itself independent of its contained elements. Arrays are distinctly different from sequence groups in this way.
A sequence can have its own initiator, and a complex element having that sequence as its content can also have its own initiator, so you could express two different initiators.
Unlike a sequence group, an array does not have its own initiator, terminator, or alignment. Those properties apply to each element occurrence of the array. To give an alignment, initiator, separator or terminator to an entire array you must enclose the element declaration for the array in a sequence group and specify the alignment, separator, initiator and terminator on the sequence group.
To prevent an infinite or very long running loop, the parsing of an array MUST terminate when the parsing of an occurrence makes no forward progress. This is detected when the following are true:
- The occurrence is a point of uncertainty;
- The position in the data does not move during the parsing of the occurrence (including any associated Separator, PrefixSeparator or PostfixSeparator region);
- The occurrence is known-to-exist with empty representation or nil representation.
An array is potentially unbounded if any of the following are true:
- dfdl:occursCountKind is 'stopValue'
- dfdl:occursCountKind is 'parsed'
- dfdl:occursCountKind is 'implicit' and XSD maxOccurs is unbounded
When dfdl:occursCountKind is 'stopValue' this results in a processing error because the stop value will never be encountered.
When parsing a single array, it is possible to extract occurrences that have different representations (nil, empty, normal, absent) although with some values of dfdl:lengthKind certain combinations of representations are not possible.
Occurrences with nil representation are added to the Infoset with [nilled] member true.
Occurrences with empty representation may or may not be added to the Infoset, as described in Section 9.5. If a required occurrence is not added to the Infoset, it may be a processing error, dependent on dfdl:occursCountKind as described in section 16.1.
Occurrences with absent representation are not added to the Infoset. For a required occurrence it may be a processing error, dependent on dfdl:occursCountKind as described in section 16.1.
Consider parsing an array where optional occurrences with empty representation are present in the data, but there are also later optional occurrences present with normal representation. Such an array is called a 'sparse array'.
If the indices of the occurrences are significant and need to be preserved, then the array may be modelled using an element with XSD nillable 'true', dfdl:nilKind 'literalValue', dfdl:nilValue '%ES;' and dfdl:nilValueDelimiterPolicy the same as dfdl:emptyValueDelimiterPolicy. The occurrences with empty representation now become occurrences with nil representation, and will produce nil values in the Infoset, so the absolute positions of all occurrences are preserved.
If the indices of the occurrences are not significant, then the array should be modelled using an element with XSD nillable 'false'. Optional occurrences with empty representation will not create items in the Infoset, so the absolute position of any optional occurrences with normal representation is not preserved. Optional occurrences with empty representation are therefore skipped.