[X3D-Public] X3D schema: adding annotations for inputOnly, outputOnly fields

[Don Brutzman]

Currently we are working on autogenerating whole sections of the Java SAI specification to show the API bindings for all X3D nodes and fields.  The X3D Schema serves as the design document and the output document is produced using an XSLT stylesheet.

References:

	X3D Specifications: DOCTYPE and Schema Validation
	http://www.web3d.org/specifications

	X3D XML Schema
	http://www.web3d.org/specifications/x3d-3.3.xsd

	X3D language bindings, Part 2: Java
	http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/X3D_Java.html

	X3D Abstract Specification: CADPart
	http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/CADGeometry.html#CADPart

Overall goal: autogenerate Appendix B Abstract node interfaces and Appendix C Concrete node interfaces.  The stylesheet being built to do this is online at

	BuildSpecificationLanguageBindingJava.xslt
	https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/BuildSpecificationLanguageBindingJava.xslt

So far, only the bindings for fields with accessType initializeOnly and inputOutput can be produced, because those are the only ones currently present in the X3D Schema.

So bindings for transient fields with accessType inputOnly and outputOnly would need to be added.

Here is the pattern I am working on, feedback is welcome if anyone else is interested in XML Schema design.

Example follows from X3D schema definition for CADPart, which is both an X3DProductStructureChildNode and also implements X3DGroupingNode:

===========================
<xs:element name="CADPart">
   <xs:annotation>
     <xs:appinfo>
       <!-- CADPart implements X3DGroupingNode but can only contain CADFace nodes -->
       <xs:attribute name="otherInterfaces" type="xs:string" fixed="X3DGroupingNode"/>
     </xs:appinfo>
     <xs:documentation source="http://www.web3d.org/files/specifications/19775-1/V3.3/Part01/components/CADGeometry.html#CADPart"/>
   </xs:annotation>
   <xs:complexType>
     <xs:complexContent>
       <xs:extension base="X3DProductStructureChildNode">

         <!-- additional contained element (node) content -->
         <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:annotation>
             <xs:documentation>children</xs:documentation>
           </xs:annotation>
           <xs:element ref="CADFace"/>
           <xs:element ref="ProtoInstance">
             <xs:annotation>
               <xs:documentation>Appropriately typed substitute node</xs:documentation>
             </xs:annotation>
           </xs:element>
         </xs:choice>

         <!-- additional contained attribute (simple-type) content, matching X3DGroupingNode -->
         <xs:attribute name="center" type="SFVec3f" default="0 0 0"/>
         <xs:attribute name="rotation" type="SFRotation" default="0 0 1 0"/>
         <xs:attribute name="scale" type="SFVec3f" default="1 1 1"/>
         <xs:attribute name="scaleOrientation" type="SFRotation" default="0 0 1 0"/>
         <xs:attribute name="translation" type="SFVec3f" default="0 0 0"/>
         <xs:attribute name="bboxCenter" type="SFVec3f" default="0 0 0"/>
         <xs:attribute name="bboxSize" type="boundingBoxSizeType" default="-1 -1 -1"/>
       </xs:extension>
     </xs:complexContent>
   </xs:complexType>
</xs:element
===========================

And so, am thinking of inserting inputOnly field interfaces such as the following, appended immediately after "otherInterfaces" above:

	<xs:attribute name="inputOnlyField" type="MFNode" fixed="addChildren"/>
	<xs:attribute name="inputOnlyField" type="MFNode" fixed="removeChildren"/>

Comment is welcome on the above construct.  Similar annotation insertions would also be inserted for outputOnly field definitions.

Since these definitions are annotations, they are usable by humans & applications but have no impact on validation of X3D scenes.  Thus any .x3d document that tries to define a value for an inputOnly or outputOnly field will still fail XML Schema validation.

This approach appears to add additional helpful information to our X3D schemas that can be looked up and used by tools.  Example use:
- Specification chapter generator, as described above
- Method-complete SAI generators for various programming languages  (Javascript, Java, Python, C++, etc.)
- X3D Tooltips
- Other tools wishing to automate suggestions for ROUTEs, check destination typing, etc.

Any feedback is appreciated on design rationale or details.  I'll continue working on it.

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