[x3d-public] updates to X3D Schema, X3DUOM: refactored names ofenumeration lists

[John Carlson]

I have added oneOf’s to the JSON schema, and will proceed with testing

John

Sent from Mail for Windows 10

From: John Carlson
Sent: Monday, October 22, 2018 12:04 PM
To: Brutzman, Donald (Don) (CIV)
Subject: Re: [x3d-public] updates to X3D Schema, X3DUOM: refactored names ofenumeration lists

I’m taking a rest.  Will look at this when I can, run the JSON schema generator etc.   mostly I’ll be looking for changes in the schema, but I will also look at X3DUOM and the schema generator.  It would be good to have a JSON file and whether it should pass schema validation or not.  If there’.s no changes to any JSON scenegraph documents, perhaps my job is already done?

On Mon, Oct 22, 2018 at 11:48 AM Brutzman, Donald (Don) (CIV) <brutzman at nps.edu> wrote:
Summary: improved support for lists of required/optional enumeration values in X3D Schema, X3DUOM, etc.

------------------------------------------------------------------------------------
1. Background.

Wikipedia: Enumerated type
https://en.wikipedia.org/wiki/Enumerated_type
"In computer programming, an enumerated type (also called enumeration, enum, or factor in the R programming language, and a categorical variable in statistics) is a data type consisting of a set of named values called elements, members, enumeral, or enumerators of the type."

A long-standing challenge in X3DJSAIL implementation of X3D Unified Object Model (X3DUOM) has been enumeration lists of string tokens.  Sometimes values are strictly limited, other times they are extensible.  Since the X3D Architecture specification strives for complete clarity whenever defining them, it will be good to handle these as precisely as possible when validating or producing X3D content..

For an example node, here is the FontStyle specification excerpted:
===================================================================
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/text.html#FontStyle
15.4.1 FontStyle

FontStyle : X3DFontStyleNode {
   MFString []       family      "SERIF"
   SFString []       language    ""
   MFString []       justify     "BEGIN" ["BEGIN","END","FIRST","MIDDLE",""]
   SFString []       style       "PLAIN" ["PLAIN"|"BOLD"|"ITALIC"|"BOLDITALIC"|""]
  [...snip...]
}
===================================================================

When you read the specification prose, it quickly becomes clear that 'family' and 'language' can be extended by end users to many font families, while 'justify' and 'style' are strictly restricted in what values are allowed.

This was hard to keep track of in X3DUOM.  It now has been addressed and support has been provided in two ways:
a. (v4.0) Refactor renaming of simpleType naming conventions in order to support X3DUOM design patterns:
     enumeration Choices (strict sets of string tokens) and
     optional Values (allowed, extendable string tokens).
b. X3DUOM now includes boolean attribute additionalEnumerationValuesAllowed in all SF/MFString fields that refer to such lists.

------------------------------------------------------------------------------------

2. Applied a naming convention.  Primary change was simply regularizing the names of existing xs:simpleType definitions in the X3D XML Schema.  These are primarily internal so they might not be used by anything other than X3DJSAIL and X3DJSONLD.  These lists are not formally defined as such in the X3D Architecture, rather they just reflect the values provided there.

Source schema and derived X3DUOM:
http://www.web3d.org/specifications/x3d-4.0.xsd
http://www.web3d.org/specifications/X3DUnifiedObjectModel-4.0.xml
http://www.web3d.org/specifications/X3DUnifiedObjectModel-4.0.json

Examples from X3D 4.0 XML Schema documentation:
FontStyle        http://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0_FontStyle.html
fontFamilyValues http://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0_fontFamilyValues.html
justifyChoices   http://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0_justifyChoices.html
fontStyleChoices http://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0_fontStyleChoices.html

Examples from X3DJSAIL documentation:
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Text/FontStyleObject.html
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Text/FontStyleObject.html#field.summary

Current X3DJSAIL work includes stricter checking or warnings (as appropriate) when setting/adding/validating new values.  The improved naming conventions and X3DUOM additionalEnumerationValuesAllowed attributes permit such work to progress further.

------------------------------------------------------------------------------------
3. These have only been applied to X3D v4.0 schema/X3DUOM in order to allow inspection and comment.

TODO will apply to v3.0-v3.3 schemas following review.  This has no direct impact on any existing X3D scene content.

All feedback welcome.  Have fun with X3D Unified Object Model (X3DUOM)!   8)

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
_______________________________________________
x3d-public mailing list
x3d-public at web3d.org
http://web3d.org/mailman/listinfo/x3d-public_web3d.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20181022/f0b35277/attachment.html>