[x3d-public] X3D minutes, 17 JAN 2020: X3Dv4 name types

[Don Brutzman]

Summary: name type checks appear to be all sorted out and deployed.  Remaining work: approve and apply spec prose below.

Resolution maintained at new mantis issue 1276 - name types: whitespace constraints, NMTOKEN and SFString.

> Specification is typically silent and schema/DOCTYPE are inconsistent regarding whether whitespace is allowed in name values.
> Clearer definitions and stricter validation support improves authoring quality
* https://www.web3d.org/member-only/mantis/view.php?id=1276
------

Looked closely at naming and whitespace, executing the discussion from last week.  Some small variations:
   
a. Maintained consistent use of xs:NMTOKEN (avoiding xs:token) so that XML schema and DOCTYPE representations are identical.
b. We can't allow whitespace in HAnim node names because they are often used to construct other identifiers, for example prepending a humanoid name "CharleChan_" or HAnimSite appending a purpose. HAnimSite name must end in '_tip' or '_view' or '_pt' suffix.

Resulting rules:
- No space allowed, type xs:NMTOKEN: Prototypes, field/fieldValue, vertex nodes (used by shader programs), UNIT, HAnim nodes
- Whitespace allowed, type SFString: CAD nodes, meta statement, Metadata nodes

Otherwise prior analysis was OK.  Didn't need to adjust DOCTYPE, it already matched.  Relaxed restrictions for meta, Metadata nodes and CAD nodes in XML schema.  Updated X3DUOM, python, java, X3D Tooltips, X3D Schematron.

Documentation also found in X3D Scene Authoring Hints, Typing of name attributes:
* https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NameTyping

Note further warning there:
"Dublin Core Metadata Initiative (DCMI) requires name to be a token appendable to a URI, so normal expectation for typical names is NMTOKEN."
* https://www.dublincore.org/specifications/dublin-core/dcmi-terms

=============================================
Suggested specification prose, please review:

4.4.3 DEF/USE semantics
4.4.4 Prototype semantics, 4.4.4.1 Introduction
4.4.2.2 Field semantics, inserted as list item g.
7.2.5.5 UNIT statement (already includes statement)
26.2 Concepts (Humanoid Animation)
31.3.1 X3DProgrammableShaderObject

   "Values for names are not allowed to contain whitespace."

=============================================
7.2.5.6 META statement (substituting <key> for name)
7.3.4 X3DMetadataObject
32.3.1 X3DProductStructureChildNode

    "Note that names are permitted to contain whitespace characters but might be inconsistent. A name value containing whitespace might not validate or match other corresponding values."

=============================================

On 1/17/2020 9:34 AM, Don Brutzman wrote:
> 
> 5.c. Prior discussion: how to we specify types in metadata sets and metadata schemas?
> 
> Pending today: can we apply/confirm these changes?
> 
> Related issue: should 'name' field be NMTOKEN or SFString?  The answer varies.  This is a shared issue for Metadata, CAD, HAnim, protos, field/fieldValue definitions, DEF/USE (type ID/IDREF), ROUTE (IDREF), IMPORT/EXPORT etc.
> 
> We had a long and interesting discussion on metadata schemes, looking at an example that Nicholas is constructing.
> 
> * Metadata example for multi-LOD laser scan
> https://docs.google.com/document/d/1c1gDggN3Qr3fHKH8oHhM8soWuX_24bT3_nsdSAxzcvw/edit?usp=sharing
> 
> Of course in all cases when considering resolution of issues, our precedence of priorities should be along the lines of
> - what is correct answer for X3Dv4,
> - potential impacts on tools and content,
> - does specification need change from X3Dv3.3,
> - best way to achieve content validation to match.
> 
> Naming conventions are especially pertinent as far as data models go.  How strict should we be with respect to names?  The X3D Abstract Specification is often silent about this, requiring interpretation or deserving better clarity.  More about naming conventions can be found in the X3D Scene Authoring Hints.
> 
> - meta Statements
> https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#metaStatements
> - Metadata Nodes
> https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#MetadataNodes
> - Naming Conventions
> https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions
> 
> The primary distinction being made in the X3D XML Schema and DOCTYPE tend to be
> - NMTOKEN (no whitespace) for names that are identifiers or strict enumerations, such as Prototype names
> - SFString (whitespace allowed) for names that are less formal.
> - ID/IDREF (unique NMTOKEN values) for DEF/USE names that have to be validated and strictly referred to (for example, by ROUTE statements).
> 
> In general, since metadata schemes by other parties can vary greatly, we agreed to *not restrict the presence of whitespace in names* that might be defined by other taxonomies and don't affect scene-graph integrity.
> 
> *For review: proposed typing of 'name' fields follows*
> 
> - No space allowed:   Prototypes, field/fieldValue, vertex nodes (used by shader programs), UNIT
> - Whitespace allowed: CAD, HAnim, meta statement, Metadata nodes
> 
> Discussion: we thought that naming of UNIT factors should be an author prerogative, but spec already says name has no whitespace:
> 
> * 7.2.5.5 UNIT statement
> https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#UNITStatement
>> A change in a base unit is specified by UNIT statements at the top of the file preceding any element content but in the statement order specified in 7.2.5.1 Organization. The form of the UNIT statement is:
>>
>>     UNIT <category> <name> <conversionFactor>
>>
>> where <category> is a string specifying one of the categories in Table 4.2, <name> is a string that does not contain whitespace that provides a name for the new default base unit, and <conversion_factor> is a positive double precision value that converts the new default base unit to the initial base unit specified in Table 4.2. Direct modification of conversion factors for derived units is not allowed.
> 
> Also noticed an inconsistency: sometimes the schema uses schema type xs:NMTOKEN and sometimes xs:token.  A close read of the XML Schema Recommendation shows that they are nearly identical, with xs:NMTOKEN defined to exactly match DOCTYPE NMTOKEN (for backwards compatibility) while xs:token has identical constraints on values, and allows further restrictions on types via a regular expression (regex) pattern.  I believe that xs:token is what we want to apply consistently in X3D XML Schema.
> 
> - W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes, 3.4.2 token
> https://www.w3.org/TR/xmlschema11-2/#token
> 
> - W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes, 3.4.4 NMTOKEN
> https://www.w3.org/TR/xmlschema11-2/#NMTOKEN
> 
> Of note is that the following pending Mantis issue, which notes that
>      7.3.4 X3DMetadataObject
> https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#X3DMetadataObject
>      "The specification of a non-empty value for the name field is required."
> 
> Recommend we keep spec unchanged and clear the following Mantis issue.
> 
> * 764: 7.3.4 X3DMetadataObject - Is name field required?
> https://www.web3d.org/member-only/mantis/view.php?id=764
>    related to issue 530, which was resolved.
> 
> Multiple TODO action items will immediately flow from these decisions.
> 
> - Review, resolve proposed typing of 'name' fields
> - Replace XML Schema xs:NMTOKEN types with SFString or xs:token, as appropriate
> - Confirm XML Schema and XML DOCTYPE match as closely as possible
> - Update X3DUOM, X3DJSAIL Java, X3DPSAIL Python, X3D Tooltips
> - Add warnings (or relax errors) to X3D Tidy and X3D Schematron, as appropriate
> - Check X3D Examples by unit testing
> 
> We agreed to proceed as summarized above.

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