XSD: questions about occurences #1513

woutdenolf · 2024-11-23T09:06:15Z

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

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

The text was updated successfully, but these errors were encountered:

prjemian · 2024-11-23T15:20:46Z

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 · 2024-11-23T15:28:46Z

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 · 2024-11-23T15:34:52Z

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 · 2024-11-23T15:44:46Z

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 · 2024-11-23T15:59:08Z

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

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

woutdenolf · 2024-11-23T16:01:02Z

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 · 2024-11-23T16:02:04Z

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

woutdenolf · 2024-11-23T16:03:54Z

"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 · 2024-11-23T16:05:14Z

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

prjemian · 2024-11-23T16:06:23Z

If it is just a change in the documentation, yes. Looks like that makes it clearer.

prjemian · 2024-11-23T16:11:46Z

Is "unbounded" an allowed valued for our (nx:) nonNegativeUnbounded type?

definitions/nxdl.xsd

Lines 1046 to 1065 in 5b6daa0

    
           <xs:simpleType name="nonNegativeUnbounded"> 
        
           	<xs:annotation> 
        
           		<xs:documentation> 
        
           			A ``nonNegativeUnbounded`` allows values including 
        
           			all positive integers, zero, and the string ``unbounded``. 
        
           			(This data type is used internally in the NXDL schema 
        
           			to define a data type.) 
        
           		</xs:documentation> 
        
           	</xs:annotation> 
        
           	<xs:union> 
        
           		<xs:simpleType> 
        
           			<xs:restriction base="xs:nonNegativeInteger"/> 
        
           		</xs:simpleType> 
        
           		<xs:simpleType> 
        
           			<xs:restriction base="xs:string"> 
        
           				<xs:enumeration value="unbounded" /> 
        
           			</xs:restriction> 
        
           		</xs:simpleType> 
        
           	</xs:union> 
        
           </xs:simpleType>

Looks as if our rules define "unbounded". Your suggestion is to make this obvious in the docstring?

woutdenolf · 2024-11-23T16:21:13Z

Looks as if our rules define "unbounded". Your suggestion is to make this obvious in the docstring?

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

<xs:complexType name="fieldType">
    <xs:complexContent>
        <xs:extension base="nx:basicComponent">
            <xs:attribute name="maxOccurs" use="optional"  default="1" type="nx:nonNegativeUnbounded">

Maybe suggestion is that "maxOccurs" needs a default since it is optional. This seems to be the case for fields (default is 1) but not for groups. Do we really have a different default for fields and groups?

prjemian · 2024-11-23T16:23:47Z

Maybe suggestion is that "maxOccurs" needs a default since it is optional.

Agreed.

We might need to keep up with the standard on flexible names. Decisions about these attributes should be reviewed.

woutdenolf · 2024-11-23T17:02:03Z

For reference, here is a table of permutations with the default value in bold. This is for fields. For groups maxOccurs does not seem to have a default (although @prjemian says it is "unbounded": #1513 (comment))

minOccurs	maxOccurs	optional	recommended	Meaning	Valid
0	1	false	false	The element is optional (may occur 0 or 1 time), and there’s no recommendation to include it.	✅
0	1	true	false	The element is optional (may occur 0 or 1 time); explicitly marked as optional.	✅
0	1	false	true	The element is optional (may occur 0 or 1 time); inclusion is recommended but not enforced.	✅
0	1	true	true	The element is optional (may occur 0 or 1 time); explicitly optional with a recommendation to include it.	✅
1	1	false	false	The element is required (must occur exactly once).	✅
1	1	false	true	The element is required (must occur exactly once), with a recommendation to include it (redundant).	✅
1	1	true	false	Contradictory: The element cannot be both required and optional.	❌
1	1	true	true	Contradictory: The element cannot be both required and optional.	❌
0	unbounded	false	false	The element is optional and can occur any number of times.	✅
0	unbounded	true	false	The element is optional, explicitly marked as such, and can occur any number of times.	✅
0	unbounded	false	true	The element is optional, can occur any number of times, and inclusion is recommended.	✅
0	unbounded	true	true	The element is optional, explicitly marked as such, can occur any number of times, and inclusion is recommended.	✅
1	unbounded	false	false	The element is required to occur at least once and may occur any number of times.	✅
1	unbounded	false	true	The element is required to occur at least once, may occur any number of times, and is recommended.	✅
1	unbounded	true	false	Contradictory: The element cannot be both required and optional.	❌
1	unbounded	true	true	Contradictory: The element cannot be both required and optional.	❌
0	0	false	false	The element cannot appear (minOccurs = 0, maxOccurs = 0).	✅
0	0	true	false	The element cannot appear, but is explicitly optional (redundant).	✅
0	0	false	true	The element cannot appear, but is recommended (contradictory).	❌
0	0	true	true	The element cannot appear, but is explicitly optional and recommended (contradictory).	❌
unbounded	unbounded	false	false	Element can occur 0 or more times.	✅
unbounded	unbounded	true	false	Element can occur 0 or more times, no recommendation.	✅
unbounded	unbounded	false	true	Element can occur 0 or more times, inclusion recommended.	✅
unbounded	unbounded	true	true	Element can occur 0 or more times, optional with recommendation.	✅

prjemian added question nxdl-syntax labels Nov 23, 2024

prjemian self-assigned this Nov 23, 2024

prjemian added this to NIAC 2024 project Nov 23, 2024

prjemian added this to the NXDL 2025 milestone Nov 23, 2024

prjemian removed this from NIAC 2024 project Nov 23, 2024

woutdenolf linked a pull request Nov 23, 2024 that will close this issue

XDS: clarify the definition of the optional attribute in relation to minOccurs for fields and groups #1514

Open

prjemian linked a pull request Nov 23, 2024 that will close this issue

XDS: clarify the definition of the optional attribute in relation to minOccurs for fields and groups #1514

Open

woutdenolf linked a pull request Nov 23, 2024 that will close this issue

maxOccurs is optional which means it has a default. #1515

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

XSD: questions about occurences #1513

XSD: questions about occurences #1513

woutdenolf commented Nov 23, 2024 •

edited

Loading

prjemian commented Nov 23, 2024 •

edited

Loading

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024

prjemian commented Nov 23, 2024 •

edited

Loading

woutdenolf commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024 •

edited

Loading

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024 •

edited

Loading

XSD: questions about occurences #1513

XSD: questions about occurences #1513

Comments

woutdenolf commented Nov 23, 2024 • edited Loading

prjemian commented Nov 23, 2024 • edited Loading

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024

prjemian commented Nov 23, 2024 • edited Loading

woutdenolf commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024 • edited Loading

prjemian commented Nov 23, 2024

woutdenolf commented Nov 23, 2024 • edited Loading

woutdenolf commented Nov 23, 2024 •

edited

Loading

prjemian commented Nov 23, 2024 •

edited

Loading

prjemian commented Nov 23, 2024 •

edited

Loading

woutdenolf commented Nov 23, 2024 •

edited

Loading

woutdenolf commented Nov 23, 2024 •

edited

Loading