[x3d-public] Action Needed: Need for acceptableStatements (or types) for children fields in X3DObject Model
Don Brutzman
brutzman at nps.edu
Sat Jul 29 15:12:10 PDT 2017
Thanks for the close scrutiny of OM4X3D and autogeneration/testing of JSON Schema, John.
BLUF recommendation: suggest you use current design patterns in existing X3D JSON Schema and we continue refining and improving everything together. In this way, multiple X3D validation designs remain coherent and consistent while refining/evolving. It is much much easier to compare to gain insight, and then incrementally improve matching approaches, than it is to reconcile divergent approaches.
Detailed analysis follows.
Sounds like you are using Object Model for X3D (OM4X3D) available at
http://www.web3d.org/specifications/X3DObjectModel-3.3.xml
The content model for contained nodes and statements is generated from the content model for X3D XML Schema, and matches both XML Schema and DTD.
http://www.web3d.org/specifications/x3d-3.3.xsd
http://www.web3d.org/specifications/X3dSchemaDocumentation3.3.html
http://www.web3d.org/specifications/x3d-3.3.dtd
http://www.web3d.org/specifications/X3dDoctypeDocumentation3.3.html
Example excerpt follows:
<AbstractNodeType name="X3DGroupingNode">
<InterfaceDefinition specificationUrl="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#X3DGroupingNode"
appinfo="Grouping nodes can contain other nodes as children, thus making up the backbone of a scene graph.">
<componentInfo name="Grouping" level="1"/>
<Inheritance baseType="X3DChildNode"/>
<AdditionalInheritance baseType="X3DBoundedObject"/>
<field type="MFNode"
accessType="inputOnly"
name="addChildren"
acceptableNodeTypes="X3DChildNode">
<componentInfo name="Grouping" level="2"/>
</field>
<field type="SFVec3f"
accessType="initializeOnly"
name="bboxCenter"
default="0 0 0"/>
<field type="SFVec3f"
accessType="initializeOnly"
name="bboxSize"
default="-1 -1 -1"
baseType="boundingBoxSizeType"/>
<field type="MFNode"
accessType="inputOutput"
name="children"
acceptableNodeTypes="X3DChildNode"/>
<field type="SFNode"
accessType="inputOutput"
name="metadata"
default="NULL"
acceptableNodeTypes="X3DMetadataObject"
inheritedFrom="X3DNode"/>
<field type="MFNode"
accessType="inputOnly"
name="removeChildren"
acceptableNodeTypes="X3DChildNode">
<componentInfo name="Grouping" level="2"/>
</field>
<field type="SFString"
accessType="inputOutput"
name="DEF"
inheritedFrom="DEF_USE"/>
<field type="SFString"
accessType="inputOutput"
name="USE"
inheritedFrom="DEF_USE"/>
<field type="SFString"
accessType="inputOutput"
name="class"
inheritedFrom="globalAttributes"/>
<ContentModel>
<GroupContentModel name="ChildContentModel" minOccurs="0" maxOccurs="unbounded"/>
<GroupContentModel name="ChildContentModelCore" minOccurs="0"/>
</ContentModel>
</InterfaceDefinition>
</AbstractNodeType>
Here is a variant example which includes both primary GroupContentModel and then specificNodeContentModel entries:
<ConcreteNode name="CADFace">
<InterfaceDefinition specificationUrl="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/CADGeometry.html#CADFace">
<componentInfo name="CADGeometry" level="2"/>
<Inheritance baseType="X3DProductStructureChildNode"/>
<AdditionalInheritance baseType="X3DBoundedObject"/>
<field type="SFVec3f"
accessType="initializeOnly"
name="bboxCenter"
default="0 0 0"/>
<field type="SFVec3f"
accessType="initializeOnly"
name="bboxSize"
default="-1 -1 -1"
baseType="boundingBoxSizeType"/>
<field type="SFNode"
accessType="inputOutput"
name="metadata"
default="NULL"
acceptableNodeTypes="X3DMetadataObject"
inheritedFrom="X3DNode"/>
<field type="SFString"
accessType="inputOutput"
name="name"
inheritedFrom="X3DProductStructureChildNode"/>
<field type="SFNode"
accessType="inputOutput"
name="shape"
default="NULL"
acceptableNodeTypes="Shape|LOD|Transform"/>
<field type="SFString"
accessType="inputOutput"
name="DEF"
inheritedFrom="DEF_USE"/>
<field type="SFString"
accessType="inputOutput"
name="USE"
inheritedFrom="DEF_USE"/>
<field type="SFString"
accessType="inputOutput"
name="class"
inheritedFrom="globalAttributes"/>
<containerFieldDefault name="children"/>
<ContentModel>
<GroupContentModel name="ChildContentModelCore" minOccurs="0"/>
<NodeContentModel name="Shape"/>
<NodeContentModel name="LOD"/>
<NodeContentModel name="Transform"/>
<NodeContentModel name="ProtoInstance"/>
</ContentModel>
</InterfaceDefinition>
</ConcreteNode>
Here is a particular statement, ROUTE:
<Statement name="ROUTE">
<InterfaceDefinition specificationUrl="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/concepts.html#ModifyingObjectsRoutes"
appinfo="ROUTE connects output fields of event-producing nodes to input fields of event-consuming nodes.">
<componentInfo name="Core" level="1"/>
<field type="SFString"
accessType="inputOutput"
name="fromField"
use="required"/>
<field type="SFString"
accessType="inputOutput"
name="fromNode"
use="required"/>
<field type="SFString"
accessType="inputOutput"
name="toField"
use="required"/>
<field type="SFString"
accessType="inputOutput"
name="toNode"
use="required"/>
</InterfaceDefinition>
</Statement>
However "ROUTE" does not appear elsewhere in OM4X3D. Its presence as a legal child node of X3DGroupingNode is implicit and can only be inferred by looking at ChildContentModel in X3D XML Schema.
As you have discovered, this appears to be an omission in the OMX3D definitions.
We certainly do want to keep everything consistent, and so precise treatment to make such a relationship explicit in OM4X3D will require further scrutiny of these design patterns, quite possibly according to the approach that you suggest. Since the X3D content model is pretty involved, and since we are working across multiple encodings and programming languages, it is good to be careful and deliberate about these things.
Of related interest is to look at how X3DJSAIL handles this relationship by using class (rather than interface) hierarchy:
=================================================================
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/ROUTEObject.html
org.web3d.x3d.jsail.Core
Class ROUTEObject
java.lang.Object
org.web3d.x3d.jsail.X3DConcreteElement
org.web3d.x3d.jsail.X3DConcreteStatement
org.web3d.x3d.jsail.Core.ROUTEObject
All Implemented Interfaces:
X3DChildNode, X3DNode
=================================================================
Note that since ROUTEObject implements X3DChildNode, it can appear within any X3D
First, it maintains the X3D interfaces from the X3D Abstract Specification (e.g. X3DChildNode, X3DNode) separate from the object hierarchy.
Second, since the abstract specification does not list interfaces for statements (root cause of this current design gap), it creates
Class X3DConcreteElement which has two concrete subclasses: X3DConcreteNode and X3DConcreteStatement.
=================================================================
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/X3DConcreteElement.html
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/package-tree.html
org.web3d.x3d.jsail
Class X3DConcreteElement
java.lang.Object
org.web3d.x3d.jsail.X3DConcreteElement
Direct Known Subclasses:
X3DConcreteNode, X3DConcreteStatement
=================================================================
After considering and trying a number of approaches, I left the X3D specification interfaces verbatim/unchanged and handled the necessary additions via this class/subclass approach. It achieves the same content model as X3D specification and XML schema with the addition of strong typing. Strong typing of elements (i.e. nodes or statements) means that creation of a valid scene graph is easily allowed (indeed with choices prompted by IDE). Meanwhile, creation of an invalid scene graph is not permitted since that would violate strong typing requirements and thus fail compilation.
Next... Looking closely at Roy's manually created X3D JSON schema is particularly important for what you are doing. Some excerpts:
=================================================================
http://www.web3d.org/specifications/x3d-3.3-JSONSchema.json
http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3.html
JSON Schema definition, Group documentation:
http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3/x3d-3.3-JSONSchema.html#Link54
"Group": {
"type": "object",
"properties": {
"@DEF": {
"type": "string"
},
"@USE": {
"type": "string"
},
"IS": {
"$ref": "#/definitions/IS"
},
"@bboxCenter": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number",
"default": 0
}
},
"@bboxSize": {
"$ref": "#/definitions/@bboxSize"
},
"-children": {
"$ref": "#/definitions/-children"
},
"-metadata": {
"$ref": "#/definitions/-metadata"
}
},
"additionalProperties": false
}
=================================================================
JSON Schema definition, CADFace documentation:
http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3/x3d-3.3-JSONSchema.html#Link12
"CADFace": {
"type": "object",
"properties": {
"@DEF": {
"type": "string"
},
"@USE": {
"type": "string"
},
"IS": {
"$ref": "#/definitions/IS"
},
"@bboxCenter": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number",
"default": 0
}
},
"@bboxSize": {
"$ref": "#/definitions/@bboxSize"
},
"@name": {
"type": "string"
},
"-metadata": {
"$ref": "#/definitions/-metadata"
},
"-shape": {
"type": "object",
"properties": {
"LOD": {
"$ref": "#/definitions/LOD"
},
"Shape": {
"$ref": "#/definitions/Shape"
},
"Transform": {
"$ref": "#/definitions/Transform"
},
"ProtoInstance": {
"$ref": "#/definitions/ProtoInstance"
}
},
"additionalProperties": false
},
"-children": {
"$ref": "#/definitions/-commentRoute"
}
},
"additionalProperties": false
},
=================================================================
JSON Schema definition -children
http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3/x3d-3.3-JSONSchema.html#Link107
(scroll down to "source code)
"-children": {
"description": "MF X3DChildNode content",
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"#comment": {
"type": "string"
},
"ProtoInstance": {
"$ref": "#/definitions/ProtoInstance"
},
"Anchor": {
"$ref": "#/definitions/Anchor"
},
"AudioClip": {
"$ref": "#/definitions/AudioClip"
},
"Background": {
"$ref": "#/definitions/Background"
},
[... many nodes skipped ...]
"VolumePickSensor": {
"$ref": "#/definitions/VolumePickSensor"
},
"WorldInfo": {
"$ref": "#/definitions/WorldInfo"
},
"ROUTE": {
"$ref": "#/definitions/ROUTE"
},
"ProtoDeclare": {
"$ref": "#/definitions/ProtoDeclare"
},
"ExternProtoDeclare": {
"$ref": "#/definitions/ExternProtoDeclare"
},
"IMPORT": {
"$ref": "#/definitions/IMPORT"
},
"EXPORT": {
"$ref": "#/definitions/EXPORT"
}
},
"additionalProperties": false
}
}
=================================================================
Point worth noting in preceding: we gave comment and ROUTE the prefix key "-children". I think we should take a similar approach for IMPORT and EXPORT if they appear within nodes that are not X3DGroupingNode.
So, hope this helps, please advise what you think.
v/r Don
On 7/29/2017 1:11 PM, John Carlson wrote:
> Are we assuming that can acceptableNodeTypes in the object model will allow for acceptableStatements? I'd like to see action on this in the object model (put the statements or abstract types for statements into acceptableNodeTypes) so I can continue with autogeneration of the JSON schema.
>
> On Jul 20, 2017 1:22 PM, "John Carlson" <yottzumm at gmail.com <mailto:yottzumm at gmail.com>> wrote:
> __ __
>
> I believe we need acceptableStatements to restrict acceptable statements for children fields in the X3D Object Model. If it’s ProtoInstance we have a acceptable statements which are comments. If no children field is found, then we have -commentRoute in JSON schema (temporarily now -childrenStatements). However if there are children, there’s no way to specify which statements are allowed. Previously, I tacked X3DChildNode above the statement inheritance hierarchy in my schema generator, which was wrong.
>
> __ __
>
> Do we need to extend this extra children field to other nodes so they can accept statements? And then just don’t support any acceptableNodeTypes for those children?____
>
> __ __
>
> Can we separate nodes and statements into separate children arrays in X3DJSON?____
>
> __ __
>
> Things to think about.____
all the best, Don
--
Don Brutzman Naval Postgraduate School, Code USW/Br brutzman at nps.edu
Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman
More information about the x3d-public
mailing list