XSD: questions about occurences

[woutdenolf]

<xs:attribute name="minOccurs" use="optional" default="0" type="nx:nonNegativeUnbounded">
	<xs:annotation>
		<xs:documentation>
			Minimum number of times this ``group`` is allowed to be present within its
			parent group.  Note each ``group`` must have a ``name`` attribute
			that is unique among all ``group`` and ``field``
			declarations within a common parent group.
		</xs:documentation>
	</xs:annotation>
</xs:attribute>
<xs:attribute name="recommended" use="optional" type="nx:NX_BOOLEAN" default="false" >
	<xs:annotation>
		<xs:documentation>
			A synonym for optional, but with the recommendation that this
			``group`` be specified.
		</xs:documentation>
	</xs:annotation>
</xs:attribute>
<xs:attribute name="optional" use="optional" type="nx:NX_BOOLEAN" default="false" >
	<xs:annotation>
		<xs:documentation>
			A synonym for minOccurs=0.
		</xs:documentation>
	</xs:annotation>
</xs:attribute>
<xs:attribute name="maxOccurs" use="optional" type="nx:nonNegativeUnbounded">
	<xs:annotation>
		<xs:documentation>
			Maximum number of times this ``group`` is allowed to be present within its
			parent ``group``.  Note each ``group`` must have a ``name`` attribute
			that is unique among all ``group`` and ``field``
			declarations within a common parent ``group``.
		</xs:documentation>
	</xs:annotation>
</xs:attribute>

1. maxOccurs does not have a default. So what does it mean when not provided?
2. Does optional="true" imply minOccurs=0? Does it says something about maxOccurs?
3. Does optional="false" imply minOccurs=1 or minOccurs>=1? Does it says something about maxOccurs?
4. Does recommended="true" imply optional="true"?
5. What does recommended="false" imply?

[prjemian]

1. maxOccurs does not have a default. So what does it mean when not provided?

In this case, positive infinity (type="nx:nonNegativeUnbounded").

definitions/nxdl.xsd

Line 509 in 5b6daa0

<xs:attribute name="maxOccurs" use="optional" type="nx:nonNegativeUnbounded">

[prjemian]

2. Does optional="true" imply minOccurs=0? ...

Yes. More than implies, the documentation states:

definitions/nxdl.xsd

Line 505 in 5b6daa0

A synonym for minOccurs=0.

... Does it says something about maxOccurs?

definitions/nxdl.xsd

Lines 509 to 518 in 5b6daa0

	<xs:attribute name="maxOccurs" use="optional" type="nx:nonNegativeUnbounded">
	<xs:annotation>
	<xs:documentation>
	Maximum number of times this ``group`` is allowed to be present within its
	parent ``group``. Note each ``group`` must have a ``name`` attribute
	that is unique among all ``group`` and ``field``
	declarations within a common parent ``group``.
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

The other definition of name="maxOccurs" states:

Must be greater than or equal to the value for the "minOccurs" attribute.

definitions/nxdl.xsd

Lines 844 to 853 in 5b6daa0

	<xs:attribute name="maxOccurs" use="optional" default="1" type="nx:nonNegativeUnbounded">
	<xs:annotation>
	<xs:documentation>
	Defines the maximum number of times this element may be used. Its
	value is confined to zero or greater. Must be greater than or equal to
	the value for the "minOccurs" attribute.
	A value of "unbounded" is allowed.
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

[prjemian]

3. Does optional="false" imply minOccurs=1 or minOccurs>=1? Does it says something about maxOccurs?

Was this answered for question 2?

definitions/nxdl.xsd

Lines 502 to 508 in 5b6daa0

	<xs:attribute name="optional" use="optional" type="nx:NX_BOOLEAN" default="false" >
	<xs:annotation>
	<xs:documentation>
	A synonym for minOccurs=0.
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

definitions/nxdl.xsd

Lines 837 to 843 in 5b6daa0

	<xs:attribute name="optional" use="optional" type="nx:NX_BOOLEAN" default="false" >
	<xs:annotation>
	<xs:documentation>
	A synonym for minOccurs=0.
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

definitions/nxdl.xsd

Lines 1034 to 1041 in 5b6daa0

	<xs:attribute name="optional" type="nx:NX_BOOLEAN" default="true">
	<xs:annotation>
	<xs:documentation>
	Is this attribute *optional* (if **true**)
	or *required* (if **false**)?
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

In this last case, the existing documentation:

Is this attribute optional (if true) or required (if false)?

could be changed. Perhaps this replacement is more clear?

With `optional="false"`, this attribute is required.
With `optional="true"`, this attribute is not required.

[prjemian]

4. Does recommended="true" imply optional="true"?

Yes.

definitions/nxdl.xsd

Lines 494 to 501 in 5b6daa0

	<xs:attribute name="recommended" use="optional" type="nx:NX_BOOLEAN" default="false" >
	<xs:annotation>
	<xs:documentation>
	A synonym for optional, but with the recommendation that this
	``group`` be specified.
	</xs:documentation>
	</xs:annotation>
	</xs:attribute>

(and two other identical instances).

The only use I see in any class definition is recommended=true (826 instances on main branch today, mostly contributed definitions).

(base) prjemian@arf:~/.../NeXus/definitions$ git grep " recommended=\"false\""
(base) prjemian@arf:~/.../NeXus/definitions$ git grep " recommended=\"true\"" | wc -l
826
(base) prjemian@arf:~/.../NeXus/definitions$ 

[prjemian]

5. What does recommended="false" imply?

Nothing. No commitment whatsoever.

As I recall, attribute name="recommended" was added (with class NXmx) to emphasize that while a particular item is optional, it is recommended to be included. Discussion from that time persuaded that optional="true" was not sufficient motivation that such item would actually be included in a data file.

One such example is for a units attribute on any numerical field. Here's one such example:

definitions/applications/NXmx.nxdl.xml

Line 488 in 5b6daa0

<field name="distance" type="NX_FLOAT" units="NX_LENGTH" recommended="true">

Follow this search for some history: https://github.com/search?q=repo%3Anexusformat%2Fdefinitions+recommended++&type=pullrequests&state=closed

[woutdenolf]

In this case, infinity

So maxOccurs="unbound" by default. Shall we make this explicit?

<xs:attribute name="maxOccurs" use="optional" type="nx:nonNegativeUnbounded" default="unbounded">

[prjemian]

Only if the nxdl.xsd file remains valid. Slight edit in this value: unbounded

[woutdenolf]

"optional" is a synonym for minOccurs=0. Does this mean?

• optional="true" is equivalent to minOccurs=0.
• optional="false" is equivalent to minOccurs>0.

Can we say this instead of the synonym statement (which I don't understand)?

[prjemian]

Again, try to validate the nxdl.xsd file with this change. I believe it is a limitation of (either) XSD or even XML itself.