[x3d-public] Topics for Discussion at JSON meeting: SFNode/MFNode field/fieldValue content - MetadataSet is similar

Don Brutzman brutzman at nps.edu
Wed Feb 24 17:44:38 PST 2016 

Hi John.  Worthy questions.

Our current JSON design has field name (containerField value) usually going straight to the key field, quoted with a hyphen (e.g. "-children").

If it makes sense to modify JSON structures, perhaps we need a utility method.  But am guessing this is more likely a candidate for X3D Javascript API.

On 2/24/2016 4:46 PM, John Carlson wrote:
> I believe, but I’m not sure that the containerField attribute can be set in the DOM or XML in the ConvertChildren function of the loader.  I may have to pass the container to the called functions, or apply it to all children of the passed in element.  I believe the latter would be incorrect because there may be more than one container node under a particular element.  See JSON to X3D: https://github.com/coderextreme/X3DJSONLD/blob/master/json2x3d.js
>
> John
>> On Feb 24, 2016, at 7:02 PM, John Carlson <yottzumm at gmail.com <mailto:yottzumm at gmail.com>> wrote:
>>
>>
>>> On Feb 24, 2016, at 6:39 PM, Don Brutzman <brutzman at nps.edu <mailto:brutzman at nps.edu>> wrote:
>>>
>>> Roy thanks for looking at this.  There appear to be some possible inconsistencies however we go on this one.  For example, a MetadataSet at top level of ProtoBody will have a "-children" key above it; similar for field/fieldValue initialization.
>>>
>>> I'm OK to stick with "-value" rather than "-children" and certainly support the strong reasons you provided.  Certainly MetadataSet is typically containerField="metadata" or containerField="value" when it appears elsewhere in the scene graph.
>>>
>>> John hopefully you are OK with that choice too?
>>>
>>
>> As far as I know I just look at the ‘-‘ in the loader.  The loader is going through massive changes though and these may affect it.  It remains to be determined how much these containerFields affect appearance, I think they appear in processing more and the execution engine. There may be some things in the proto expander which depend on a longer string though.   I am okay with it.  Metadata is new to me.  I will need some examples to go from, and how if at all, the appearance is affected.  All this said, will containerFields appear as attributes in JSON or will I need to put them there for the conversion to DOM or XML?  What is the rule for putting containerFields in XML attributes from the JSON?  If there’s a rule I need to create, then now’s a good time to discuss it.
>>
>>> Confirming JSON implications:  MetadataSet can contain, in any order,
>>> -  one "-metadata" key for its own self-referential metadata
>>> - one "-value"    key for zero-to-many Metadata* nodes
>>> - one "-children" key for immediate contained comments
>>>
>>> To get this to work again in the conversion stylesheet, I had to remove 2 clauses for treating "-children" similarly, lines looking like
>>>
>>> preceding-sibling::*[$parentName = 'MetadataSet'][$fieldName = 'children'] |
>>>
>>> This likely also bears on the open issue about whether to allow Metadata* nodes as top-level children of the Scene root.
>>>
>>> I refactored the attached example to only allow Metadata* nodes with containerField='metadata' or  containerField='value'.  Hence none of them are at the root any more, they are all contained within MetadataSet inside a root WorldInfo.
>>>
>>> JSON converter works OK on this one, have refreshed and checked the rest of the examples, they mostly look OK to me.  Confirmation welcome.
>>>
>>> Aha, found a new problem:  ProtoInstance is not included in Schema as an allowed child of MetadataSet.  Test scene is
>>> http://www.web3d.org/x3d/content/examples/Basic/development/SchemaTest.x3d
>>>
>>> To get this modified correctly in X3D XML Schema, I think we
>>> - do not  add ProtoInstance into ChildContentModelCore, has too many ripple side effects
>>> - instead add ProtoInstance as a part of a choice, together with ChildContentModelCore, all within MetadataSet
>>>
>>> Meanwhile DTD/DOCTYPE is OK, MetadataSet allows ProtoInstance children:
>>> http://www.web3d.org/specifications/X3dDoctypeDocumentation3.3.html#MetadataSet
>>>
>>> So... maybe we should meet Thursday (as we usually do Thursdays, instead of cancelling this week) to discuss this further.  Your call.
>>>
>>> If possible it would also be good to finally resolve whether Metadata nodes can be at top-level under Scene, presumably this also relates to your Metadata object model mantis issue.
>>>
>>> Anyway here is candidate modified schema construct for MetadataSet:
>>>
>>> <xs:element name="MetadataSet">
>>> <xs:annotation>
>>> <xs:appinfo>
>>> <xs:element name="value" type="MFNode" fixed="inputOutputField" default="X3DMetadataObject"/>
>>> <xs:element name="metadata" type="SFNode" fixed="inputOutputField" default="X3DMetadataObject"/>
>>> <xs:attribute name="additionalInterface" type="xs:string" default="X3DMetadataObject"/>
>>> <xs:attribute name="componentName" type="xs:NMTOKEN" fixed="Core"/>
>>> <xs:attribute name="componentLevel" type="xs:positiveInteger" fixed="1"/>
>>> </xs:appinfo>
>>> <xs:documentation source="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#MetadataSet"/>
>>> </xs:annotation>
>>> <xs:complexType>
>>> <xs:sequence>
>>> <xs:element ref="IS" minOccurs="0"/>
>>> <xs:choice>
>>> <xs:group ref="ChildContentModelCore" minOccurs="0" maxOccurs="unbounded"/>
>>> <xs:element ref="ProtoInstance" minOccurs="0"/>
>>> </xs:choice>
>>> </xs:sequence>
>>> <xs:attributeGroup ref="DEF_USE"/>
>>> <xs:attributeGroup ref="globalAttributes"/>
>>> <xs:attribute name="name" type="SFString"/>
>>> <xs:attribute name="reference" type="SFString"/>
>>> <xs:attribute name="containerField" type="xs:NMTOKEN" default="metadata">
>>> <xs:annotation>
>>> <xs:appinfo>Default containerField='metadata' when providing information about the parent element itself, otherwise apply containerField='value' when this element contains payload metadata inside a parent/ancestor MetadataSet element.</xs:appinfo>
>>> </xs:annotation>
>>> </xs:attribute>
>>> <!-- TODO: both X3DMetadataObject and MetadataSet need to allow optional child Metadata nodes, so child model content has to be combined to avoid collisions. -->
>>> <!-- TODO:  see X3DMetadataObject definition for potential change to X3DMetadataNode. -->
>>> </xs:complexType>
>>> </xs:element>
>>>
>>>
>>>
>>> On 2/24/2016 11:29 AM, Roy Walmsley wrote:
>>>> Don,
>>>>
>>>> Sorry for not latching onto this earlier.
>>>>
>>>> Today, when reviewing John's latest test results, I saw that MetadataSet examples were failing to validate. I checked into why, and saw that you had assigned them to a "-children" field. So I took this out of the stylesheet, so that now they are placed into either "-metadata" or "-value", depending on the containerField setting. When I regenerated them the examples were then correctly validating. I committed the change to SourceForge.
>>>>
>>>> Then you highlighted this mail to me  ...
>>>>
>>>> I'm sorry but I have to disagree with you on this one.
>>>>
>>>> My personal opinion is that the JSON should align with the abstract specification 19775-1. In that specification MetadataSet does not have a "children" field, it has a "value" field. So a  JSON encoded example should reflect the same. When we write the JSON encoding specification 19776-5 it will have to align with the abstract specification. It would be confusing to have different names for the same field in different encodings.
>>>>
>>>> I can understand the inconsistency over the different uses of the field name "value". If we want to change it we should raise a specification comment and Mantis issue, then follow procedure to consider whether to implement the change, which could then be applied to all encodings.
>>>>
>>>> Regards,
>>>>
>>>> Roy
>>>>
>>>> -----Original Message-----
>>>> From: Don Brutzman [mailto:brutzman at nps.edu]
>>>> Sent: 20 February 2016 17:39
>>>> To: John Carlson; Roy Walmsley
>>>> Cc: X3D Graphics public mailing list
>>>> Subject: Re: [x3d-public] Topics for Discussion at JSON meeting: SFNode/MFNode field/fieldValue content - MetadataSet is similar
>>>>
>>>> Another node that needs to be treated similarly:  MetadataSet has child Metadata* nodes.
>>>>
>>>> Instead of using a key "-value" the conversion now makes it "-children" for a consistent pattern with field/fieldValue content.
>>>>
>>>> Example attached.  Update to stylesheet is committed.
>>>>
>>>> p.s. yesterday's updates (adding meta warnings to all .json files) are all uploaded.
>>>>
>>>>
>>>> On 2/10/2016 10:02 AM, Don Brutzman wrote:
>>>>> Followup for email thread:  we chose -children (for greater
>>>>> simplicity/consistency) rather than -value
>>>>>
>>>>> On 2/8/2016 3:03 PM, John Carlson wrote:
>>>>>> I would prefer if simple type was @value, but I can change it to -value for JSON if desired.
>>>>>>
>>>>>> John
>>>>>>> On Feb 7, 2016, at 12:50 AM, Don Brutzman <brutzman at nps.edu <mailto:brutzman at nps.edu> <mailto:brutzman at nps.edu>> wrote:
>>>>>>>
>>>>>>> Same pattern throughout for field, fieldValue:
>>>>>>>
>>>>>>> - simple-type content goes in @value attribute for XML, "-value" key
>>>>>>> for JSON
>>>>>>>
>>>>>>> - contained node/statement/comment content is embedded in element
>>>>>>> for XML, goes in "-children" field for JSON
>>>>>>>
>>>>>>>
>>>>>>> On 2/6/2016 4:05 PM, Roy Walmsley wrote:
>>>>>>>> Don,
>>>>>>>>
>>>>>>>> I don't have any problem with that. What about for default values within a field in a ProtoInterface? Or a Shader? Or a Script?
>>>>>>>>
>>>>>>>> Roy
>>>>>>>>
>>>>>>>> -----Original Message-----
>>>>>>>> From: Don Brutzman [mailto:brutzman at nps.edu]
>>>>>>>> Sent: 06 February 2016 23:11
>>>>>>>> To: Roy Walmsley; John Carlson
>>>>>>>> Cc: x3d-public at web3d.org <mailto:x3d-public at web3d.org> <mailto:x3d-public at web3d.org>
>>>>>>>> Subject: Re: [x3d-public] Topics for Discussion at JSON meeting:
>>>>>>>> SFNode/MFNode field/fieldValue content, ProtoBody, regexes
>>>>>>>>
>>>>>>>> Testing reconsideration:  using "-value" for children SFNode/MFNode content inside a fieldValue can be improved.
>>>>>>>>
>>>>>>>> Better: use "-children" instead.  Common semantics, simpler encoding rules, easier to remember, less failure prone.
>>>>>>>>
>>>>>>>> Next version (test suite in progress) will use "-children" instead of "-value" for contained content.
>>>>>>>>
>>>>>>>> Test suite conversion checks appear to be performing well, update should be complete late tonite.
>>>>>>>>
>>>>>>>> Examples attached.  As always, comments are welcome.
>>>>>>>>
>>>>>>>> p.s. here's one comment:  i had great trouble getting "-value" to work properly.  "-children" fell right into place and seems like an obvious improvement, since the earlier "-value" was an arbitrary choice.
>>>>>>>>
>>>>>>>>
>>>>>>>> On 2/5/2016 7:04 PM, Don Brutzman wrote:
>>>>>>>>> Summary: Once again the X3D JSON design is looking pretty solid, and our tool suites are pretty powerful at detecting edge-case issues.
>>>>>>>>>
>>>>>>>>> On 2/5/2016 10:37 AM, Don Brutzman wrote:
>>>>>>>>>> [correction: shifted to x3d-public] [...] On 2/4/2016 10:56 AM,
>>>>>>>>>> Roy Walmsley wrote:
>>>>>>>>>>> Topics for Discussion for JSON encoding meeting February 5^th 2016 at 1000 PST, 1800 GMT.
>>>>>>>>>>> [...]
>>>>>>>>>>> 2) *Encoding of node fields in ‘field’ and ‘fieldValue’ elements
>>>>>>>>>>> within Script and Prototypes.* [...snip/shuffle...] Illustration
>>>>>>>>>>> of
>>>>>>>>>>> 2) above is in X3D Example Archives: Basic, CAD, Cad Geometry
>>>>>>>>>>> Extern Prototypes (see
>>>>>>>>>>> http://www.web3d.org/x3d/content/examples/Basic/CAD/_pages/page0
>>>>>>>>>>> 2.ht
>>>>>>>>>>> ml)
>>>>>>>>>>>
>>>>>>>>>>> Find the ProtoInstance named ‘IndexedQuadSet’. It has two fieldValue children. The second has the name ‘coord’, and a child Coordinate node. When converted into JSON this Coordinate node is allocated to a field /-coord/, which is the default containerField name for this node. This is incorrect. It should be allocated to the /-value/ field. This is because the element fieldValue has attributes of ‘name’ and ‘value’.
>>>>>>>>>>>
>>>>>>>>>>> A similar issue arises with default values for node fields within the field element.
>>>>>>>>>
>>>>>>>>> OK this change is worth close scrutiny to avoid confusion later.
>>>>>>>>>
>>>>>>>>> For <field> and <fieldValue>, when the "@value" attribute is used for simple types, everything works OK.
>>>>>>>>>
>>>>>>>>> For <field> and <fieldValue>, with contained SFNode/MFNode content or contained comments or contained ROUTEs, the key is now "-value" (hyphen instead of ampersand).
>>>>>>>>> [...]
>>>>>>>>
>>>>>>>> Summary, revising the prior sentence:
>>>>>>>>
>>>>>>>> For <field> and <fieldValue>, with contained SFNode/MFNode content or contained comments or contained ROUTEs, the key is now "-children" as with most other child content.
>>>
>>> all the best, Don
>>> --
>>> Don Brutzman  Naval Postgraduate School, Code USW/Br brutzman at nps.edu <mailto: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
>>> <MetadataExamples.html><MetadataExamples.json><MetadataExamples.x3d>
>>
>


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