[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 15:39:14 PST 2016
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?
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>> 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>
>>>>> 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
Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20160224/f295adf3/attachment-0001.html>
-------------- next part --------------
{ "X3D": {
"@profile":"Immersive",
"@version":"3.3",
"@xsd:noNamespaceSchemaLocation":"http://www.web3d.org/specifications/x3d-3.3.xsd",
"head": {
"meta": [
{
"@name":"title",
"@content":"MetadataExamples.x3d"
},
{
"@name":"description",
"@content":"Simple examples of meta statements, comments, WorldInfo node and typed metadata nodes."
},
{
"@name":"creator",
"@content":"Don Brutzman"
},
{
"@name":"created",
"@content":"30 September 2011"
},
{
"@name":"modified",
"@content":"24 February 2016"
},
{
"@name":"info",
"@content":"Information in head and meta elements is retained after a scene is parsed and loaded, and can be referenced via the Scene Access Interface (SAI) or Document Object Model (DOM)"
},
{
"@name":"info",
"@content":"Authoring note: MetadataBoolean requires X3D version 3.3, as used in this example scene"
},
{
"@name":"reference",
"@content":"The following referenced chapter is published online but was not included in the printed book."
},
{
"@name":"reference",
"@content":"Chapter15-MetadataInformation.html"
},
{
"@name":"reference",
"@content":"http://x3dgraphics.com/chapters/Chapter15-MetadataInformation.html"
},
{
"@name":"reference",
"@content":"http://X3dGraphics.com"
},
{
"@name":"reference",
"@content":"http://www.web3d.org/x3d/content/examples/X3dResources.html"
},
{
"@name":"rights",
"@content":"Copyright 2006, Daly Realism and Don Brutzman"
},
{
"@name":"subject",
"@content":"X3D book, X3D graphics, X3D-Edit, http://www.x3dGraphics.com"
},
{
"@name":"identifier",
"@content":"http://X3dGraphics.com/examples/X3dForWebAuthors/Chapter15-Metadata/MetadataExamples.x3d"
},
{
"@name":"generator",
"@content":"X3D-Edit 3.3, https://savage.nps.edu/X3D-Edit"
},
{
"@name":"license",
"@content":"../license.html"
},
{
"@name":"translated",
"@content":"24 February 2016"
},
{
"@name":"generator",
"@content":"X3dToJson.xslt, http://www.web3d.org/x3d/stylesheets/X3dToJson.html"
},
{
"@name":"warning",
"@content":"An experimental version of X3D JSON encoding is used for this scene. Status online at http://www.web3d.org/wiki/index.php/X3D_JSON_Encoding"
}
]
},
"Scene": {
"-children":[
{ "#comment":"Comments can appear between nodes (XML elements) but are not retained after a scene is parsed and loaded"
},
{ "#comment":"No Metadata nodes are allowed at top level of Scene graph"
},
{ "WorldInfo":
{
"@DEF":"MyWorldInfo",
"@info":["Metadata strings","can go here","as,string,array,values"],
"@title":"MetadataExamples.x3d Example Scene",
"-children":[
{ "#comment":"Structured information can go in Metadata nodes. Note that any X3D node can contain a single Metadata node with containerField='metadata'"
}
],
"-metadata":
{ "MetadataSet":
{
"@name":"Metadata_name",
"@DEF":"MyMetadataSetNode",
"@reference":"Standard 1.2.3c",
"-children":[
{ "#comment":"MetadataSet can also contain multiple Metadata nodes with containerField='value'"
}
],
"-value":[
{ "MetadataBoolean":
{
"@name":"Coin Flip",
"@DEF":"MyMetadataBooleanNode",
"@reference":"MetadataBoolean allowed in X3D v3.3 and later",
"@value":[true,false,true,false]
}
},
{ "MetadataDouble":
{
"@name":"Metadata_name",
"@DEF":"MyMetadataDoubleNode",
"@reference":"Standard 1.2.3c",
"@value":[3.141592658,2.71812181]
}
},
{ "MetadataFloat":
{
"@name":"Metadata_name",
"@DEF":"MyMetadataFloatNode",
"@reference":"Standard 1.2.3c",
"@value":[9.8,6.023e+23]
}
},
{ "MetadataInteger":
{
"@name":"Metadata_name",
"@DEF":"MyMetadataIntegerNode",
"@reference":"Standard 1.2.3c",
"@value":[6,28,496]
}
},
{ "MetadataString":
{
"@name":"Metadata_name",
"@DEF":"MyMetadataStringNode",
"@reference":"Standard 1.2.3c",
"@value":["Part 27","P27","p27"]
}
}
],
"-metadata":
{ "MetadataSet":
{
"@name":"TestNestedMetadataSetNodes",
"@DEF":"NestedMetadataSetNode",
"-value":[
{ "MetadataString":
{
"@USE":"MyMetadataStringNode"
}
},
{ "MetadataInteger":
{
"@USE":"MyMetadataIntegerNode"
}
},
{ "MetadataFloat":
{
"@USE":"MyMetadataFloatNode"
}
},
{ "MetadataFloat":
{
"@name":"coefficients",
"@value":[3.141592653,2.7128,1,0]
}
}
]
}
}
}
}
}
},
{ "Background":
{
"@skyColor":[0,0.439216,0.760784]
}
},
{ "Viewpoint":
{
"@description":"View scene source to see metadata examples",
"@position":[0,0,9]
}
},
{ "Anchor":
{
"@description":"view pretty-print scene source",
"@parameter":["target=_blank"],
"@url":["MetadataExamples.html","http://X3dGraphics.com/examples/X3dForWebAuthors/Chapter15-Metadata/MetadataExamples.html"],
"-children":[
{ "Shape":
{
"-geometry":
{ "Text":
{
"@string":["View scene source","to see","metadata,examples"],
"-fontStyle":
{ "FontStyle":
{
"@justify":["MIDDLE","MIDDLE"]
}
}
}
},
"-appearance":
{ "Appearance":
{
"-material":
{ "Material":
{
"@diffuseColor":[1,0.992157,0.039216]
}
}
}
}
}
}
]
}
}
]
}
}
}
-------------- next part --------------
A non-text attachment was scrubbed...
Name: MetadataExamples.x3d
Type: model/x3d+xml
Size: 4528 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20160224/f295adf3/attachment-0001.x3d>
More information about the x3d-public
mailing list