<div dir="ltr">Thanks for all scrutiny.   Answers and links for many of the questions follow.<div><br></div><div>1. First:  X3D version 4.0 is authoritative.  X3D version 4.1 is draft and collects a variety of changes, with details discussed on mailing lists and progress synopsized in Mantis.  Updating the online draft to match best-case understandings to date has been very helpful.  Each addiotion/deletion change in the 4.1 draft is carefully marked up and cross-referenced using Mantis, so that all evolution from X3D version 4.0 is immediately obvious.</div><div><ul><li>X3D version 4.1 draft Architecture</li><li><a href="https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/Architecture.html">X3D Architecture 4.1 draft — ISO/IEC 19775-1:202x — X3D Architecture index page</a></li></ul></div><div>More broadly, all specifications are linked and maintained up to date on the X3D Progress page.</div><div><ul><li>X3D Standards Progress</li><li><a href="https://www.web3d.org/x3d/progress">https://www.web3d.org/x3d/progress</a></li></ul><div>2. Second:  the motivation for <i>appinfo</i> and <i>documentation </i>annotations is pretty straightforward.  The X in X3D stands for Extensible, and one of our major mechanisms for that is prototype declaration.  Essentially prototypes define new nodes as a combination of existing nodes plus scripting.  Documenting such new designs is important for understanding and for correct implementation.</div></div><div><br></div><div>The approach used by World Wide Web Consortium (W3C) for defining such new elements is well developed and well implemented as part of the XML Schema specification.</div><div><ul><li>W3C XML Schema</li><li><a href="https://www.w3.org/XML/Schema">https://www.w3.org/XML/Schema</a></li><li>W3C XML Schema Definition Language (XSD) 1.1 Part 1, section 3.15 Annotations</li><li><a href="https://www.w3.org/TR/xmlschema11-1/#cAnnotations">https://www.w3.org/TR/xmlschema11-1/#cAnnotations</a></li><li>"Annotations provide for human- and machine-targeted annotations of schema components."</li></ul><div>Given this motivation, and given that this well-developed and well-supported approach for new-element annotations has been proven in W3C Schema, it was a natural thing for us to follow the same design pattern in the X3D XML Encoding. (Pretty helpful too, we didn't have to reinvent that wheel.) Having shown that, we generalized it in the X3D Architecture (as part of 4.0, I believed).  As Michalis pointed out,</div></div><div><ul><li>X3D Architecture 4.0, clause 4 Concepts, 4.4.4.2 PROTO interface declaration semantics</li><li>"Prototype and field declarations may optionally include <i>appinfo </i>functional descriptions (i.e., tooltip summary) and a <i>documentation </i>url providing a link to further related information."</li><li><a href="https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics">https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics</a></li></ul><div>Given that functional definition, we already have good patterns for equivalently representing the same information in XML, ClassicVRML, VRML, JSON, and programming languages.  One of many examples in our archives:</div></div><div><ul><li>X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14 Prototypes</li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes</a></li><li>X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14 Prototypes, Heads Up Display Example</li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExampleIndex.html">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExampleIndex.html</a></li><li><span style="color:rgb(0,0,0);font-family:"Times New Roman";font-size:medium"> </span><span title="ExternProtoDeclare refers to a ProtoDeclare node declaration provided in another file" style="color:rgb(0,0,0);font-family:"Times New Roman";font-size:medium;background-color:rgb(255,238,255)"><<span class="gmail-prototype" style="color:purple">ExternProtoDeclare</span> <span class="gmail-attribute" style="color:green">name</span>='<span class="gmail-prototype" style="color:purple">HeadsUpDisplay</span>' <span title="application information for this ExternProtoDeclare"><span class="gmail-gray" style="color:gray">appinfo</span>='<span class="gmail-value" style="color:teal">Heads-up display (HUD) keeps child geometry aligned on screen in a consistent location</span>'</span>   <span title="uniform resource locator (url) list of relative or absolute file addresses, performed in order until resource retrieval succeeds"><span class="gmail-attribute" style="color:green">url</span>=' "<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay" target="_blank">HeadsUpDisplayPrototype.x3d#HeadsUpDisplay</a>" "<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay" target="_blank">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay</a>" "<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay" target="_blank">HeadsUpDisplayPrototype.wrl#HeadsUpDisplay</a>" "<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay" target="_blank">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay</a>" '</span>></span></li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.html#21">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.html#21</a></li></ul><div>Multiple examples are shown there for many of our file encodings and programming APIs - XML, classicVRML, binary, JSON, Turtle, Java, Python.  For example, JSON:</div></div><div><br></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px"><div>          { "ExternProtoDeclare":</div><div>            {</div><div>              "@name":"HeadsUpDisplay",</div><div>              "@appinfo":"Heads-up display (HUD) keeps child geometry aligned on screen in a consistent location",</div><div>              "@url":["HeadsUpDisplayPrototype.x3d#HeadsUpDisplay","<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay</a>","HeadsUpDisplayPrototype.wrl#HeadsUpDisplay","<a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay</a>"],</div><div><br></div></blockquote>Looking ahead, formalizing JSON and all the other file-encoding specifications is our objective for 2025.  We already have mature drafts for XML, ClassicVRML and X3D Binary; probably JSON will be next effort.<div><br></div><div>3. Third, the addition of a DESCRIPTION statement for IMPORT/EXPORT has been proposed and we are currently working on a possible way to do this.  Thanks Holger for noting the draft 4.1 changes, we are tracking in Mantis (accessible to Web3D Members) and will bring this forward for group review + comment in the near future.</div><div><ul><li>Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D Architecture 4.1</li><li><a href="https://mantis.web3d.org/view.php?id=1470">https://mantis.web3d.org/view.php?id=1470</a></li></ul><div>Am very appreciative of excellent interest and scrutiny.  The appinfo and documentation definitions for prototypes and fields seems to be a quite valuable part of X3D extensibility, making new capabilities well documented and re-usable in the long term.  Conceptual improvements and issue identification/resolution are always welcome.</div><div><br></div><div>Have fun with well-documented X3D extensibility!  😀👍</div><div><br></div><div>all the best, Don</div><div><br></div><div><br></div></div></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Thu, Aug 21, 2025 at 5:20 AM Holger Seelig via x3d-public <<a href="mailto:x3d-public@web3d.org">x3d-public@web3d.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><p style="color:rgb(0,0,0)">To add fuel to the fire, X3D 4.1 now defines a DESCRIPTION string for IMPORT and EXPORT that must be parsed, currently for Classic Encoding. This description overlaps significantly with appInfo or documentation attributes.</p><p style="color:rgb(0,0,0)">On the other hand, it has not yet been specified how this DESCRIPTION should be encoded in JSON and XML, but it will certainly be similar.</p><a href="https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement" target="_blank">https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement</a><p><font color="#000000"><span></span></font></p><div>
<div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div dir="auto" style="text-align:start;text-indent:0px"><div style="color:rgb(0,0,0);letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><a href="https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement" target="_blank">https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement</a></div><div style="color:rgb(0,0,0);letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><br></div><div style="color:rgb(0,0,0);letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none">Best regards,</div><div style="color:rgb(0,0,0);letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none">Holger</div><div style="color:rgb(0,0,0);letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><br></div></div></div></div></div></div></div></div></div></div></div></div></div><div>
<div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><div>—<br>Holger Seelig<br>Leipzig, Germany<br><br><a href="mailto:holger.seelig@yahoo.de" target="_blank">holger.seelig@yahoo.de</a><br><a href="https://create3000.github.io/x_ite/" target="_blank">https://create3000.github.io/x_ite/</a><br><a href="https://patreon.com/X_ITE" target="_blank">https://patreon.com/X_ITE</a><br></div><div><br></div></div><br>
</div>
<div><br><blockquote type="cite"><div>Am 21.08.2025 um 12:42 schrieb Michalis Kamburelis via x3d-public <<a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a>>:</div><br><div><div>Thank you -- but that's not yet enough :)<br><br>The fact that appinfo is SFString says what information it can carry<br>(OK, 1 string), but not yet how it's encoded. If "appinfo" would be a<br>regular field inside a regular X3D node, it would be all we need...<br>alas, it is not.<br><br>As it stands, "appinfo" is part of "ProtoDeclare" and "field" in<br>prototype interface -- these are special concepts with special syntax,<br>in both X3D XML and classic encodings.<br><br>- For the X3D 3.3 classic encoding, this is the relevant section:<br><a href="https://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/concepts.html#PROTOStatementSyntax" target="_blank">https://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/concepts.html#PROTOStatementSyntax</a><br><br>- For the X3D 3.3 XML encoding, this is the relevant section:<br><a href="https://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/concepts.html#PrototypeAndFieldDeclarationSyntax" target="_blank">https://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/concepts.html#PrototypeAndFieldDeclarationSyntax</a><br><br>I think we need "X3D 4.0 classic encoding" and "X3D 4.0 XML encoding"<br>specs and they should extend above sections to include how the<br>additional X3D 4.0 information ("appinfo", "documentation") is<br>encoded.<br><br>The XML encoding is kind of obvious in this case (as "ProtoDeclare"<br>and "field" are XML elements, so "appinfo" and "documentation" can be<br>just XML attributes), so it's not a big question. But classic encoding<br>of them is really unknown, at least to me :)<br><br>Regards,<br>Michalis<br><br>wt., 19 sie 2025 o 18:59 John Carlson via x3d-public<br><<a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a>> napisał(a):<br><blockquote type="cite"><br>What I meant to say is appinfo is an SFString, but I don’t know if that’s enough information for the classic encoding.  Anyone?<br><br>John<br><br>On Tue, Aug 19, 2025 at 11:17 AM John Carlson <<a href="mailto:yottzumm@gmail.com" target="_blank">yottzumm@gmail.com</a>> wrote:<br><blockquote type="cite"><br>Sorry, I the previous message contained 2 large images.<br><br>The direct links are:<br><br><a href="https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare.appinfo" target="_blank">https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare.appinfo</a><br><br><br><a href="https://www.web3d.org/x3d/content/X3dTooltips.html#field.appinfo" target="_blank">https://www.web3d.org/x3d/content/X3dTooltips.html#field.appinfo</a><br><br>John<br><br>---------- Forwarded message ---------<br>From: John Carlson <<a href="mailto:yottzumm@gmail.com" target="_blank">yottzumm@gmail.com</a>><br>Date: Tue, Aug 19, 2025 at 10:54 AM<br>Subject: Re: [x3d-public] appinfo attribute/field<br>To: Michalis Kamburelis <<a href="mailto:michalis.kambi@gmail.com" target="_blank">michalis.kambi@gmail.com</a>><br>CC: Extensible 3D (X3D) Graphics public discussion <<a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a>><br><br><br>Michalis:<br><br>Tooltips may help again here, they are SFStrings.   I don’t know the meaning of CDATA or #IMPLIED though, see attached images.  The issue you mentioned contains direct links, FMI.<br><br>Thanks,<br><br>John<br><br><br>On Tue, Aug 19, 2025 at 10:46 AM Michalis Kamburelis <<a href="mailto:michalis.kambi@gmail.com" target="_blank">michalis.kambi@gmail.com</a>> wrote:<br><blockquote type="cite"><br>Let me add another question to this thread: Where is the specification<br>of how to *encode* appinfo information in the X3D classic encoding?<br><br>To add some background/context to this question:<br><br>- Thanks to John pointing out in<br><a href="https://github.com/castle-engine/castle-engine/issues/688" target="_blank">https://github.com/castle-engine/castle-engine/issues/688</a> , in CGE we<br>lack support for "appinfo" attribute in ProtoDeclare / field.<br><br>- I found a mention of new "appinfo" and "documentation" in the<br>abstract X3D 4.0 spec:<br><a href="https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics" target="_blank">https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics</a><br>,"""Prototype and field declarations may optionally include appinfo<br>functional descriptions (i.e., tooltip summary) and a documentation<br>url providing a link to further related information."""<br><br>- However, as the above is the "abstract" part of the spec ("X3D<br>Abstract : Architecture and base components") so it naturally doesn't<br>say how these "appinfo" and "documentation" are actually encoded. The<br>official XML encoding and classic encoding specs are now at 3.3<br>version -- so they don't mention how to encode this new X3D 4.0<br>feature.<br><br>- For XML encoding, it seems straightforward, judging from the<br>testcase in <a href="https://github.com/castle-engine/castle-engine/issues/688" target="_blank">https://github.com/castle-engine/castle-engine/issues/688</a><br>. They are just XML attributes.<br><br>    <ProtoDeclare appinfo='...' name='...' ...><br><br>    <field appinfo='...' ...>'<br><br>    OK, so XML encoding is simple enough:)<br><br>- We need to know how to encode this information in X3D classic, to<br>enable lossless conversion between X3D encodings (classic, XML etc.).<br><br>- If there is a spec, and/or a clear example of how to do this in X3D<br>classic encoding, please point me to it :) Thank you!<br><br>Regards,<br>Michalis<br></blockquote></blockquote><br>_______________________________________________<br>x3d-public mailing list<br><a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a><br><a href="http://web3d.org/mailman/listinfo/x3d-public_web3d.org" target="_blank">http://web3d.org/mailman/listinfo/x3d-public_web3d.org</a><br></blockquote><br>_______________________________________________<br>x3d-public mailing list<br><a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a><br><a href="http://web3d.org/mailman/listinfo/x3d-public_web3d.org" target="_blank">http://web3d.org/mailman/listinfo/x3d-public_web3d.org</a><br></div></div></blockquote></div><br></div>_______________________________________________<br>
x3d-public mailing list<br>
<a href="mailto:x3d-public@web3d.org" target="_blank">x3d-public@web3d.org</a><br>
<a href="http://web3d.org/mailman/listinfo/x3d-public_web3d.org" rel="noreferrer" target="_blank">http://web3d.org/mailman/listinfo/x3d-public_web3d.org</a><br>
</blockquote></div>