[x3d-public] appinfo attribute/field
Don Brutzman
don.brutzman at gmail.com
Thu Aug 21 10:24:17 PDT 2025
Thanks for all scrutiny. Answers and links for many of the questions
follow.
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.
- X3D version 4.1 draft Architecture
- X3D Architecture 4.1 draft — ISO/IEC 19775-1:202x — X3D Architecture
index page
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/Architecture.html>
More broadly, all specifications are linked and maintained up to date on
the X3D Progress page.
- X3D Standards Progress
- https://www.web3d.org/x3d/progress
2. Second: the motivation for *appinfo* and *documentation *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.
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.
- W3C XML Schema
- https://www.w3.org/XML/Schema
- W3C XML Schema Definition Language (XSD) 1.1 Part 1, section 3.15
Annotations
- https://www.w3.org/TR/xmlschema11-1/#cAnnotations
- "Annotations provide for human- and machine-targeted annotations of
schema components."
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,
- X3D Architecture 4.0, clause 4 Concepts, 4.4.4.2 PROTO interface
declaration semantics
- "Prototype and field declarations may optionally include *appinfo
*functional
descriptions (i.e., tooltip summary) and a *documentation *url providing
a link to further related information."
-
https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics
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:
- X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14
Prototypes
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes
- X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14
Prototypes, Heads Up Display Example
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExampleIndex.html
- <ExternProtoDeclare name='HeadsUpDisplay' appinfo='Heads-up display
(HUD) keeps child geometry aligned on screen in a consistent location'
url=' "HeadsUpDisplayPrototype.x3d#HeadsUpDisplay
<https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay>"
"
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay"
"HeadsUpDisplayPrototype.wrl#HeadsUpDisplay
<https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay>"
"
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay"
'>
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.html#21
Multiple examples are shown there for many of our file encodings and
programming APIs - XML, classicVRML, binary, JSON, Turtle, Java, Python.
For example, JSON:
{ "ExternProtoDeclare":
{
"@name":"HeadsUpDisplay",
"@appinfo":"Heads-up display (HUD) keeps child geometry
aligned on screen in a consistent location",
"@url":["HeadsUpDisplayPrototype.x3d#HeadsUpDisplay","
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay
","HeadsUpDisplayPrototype.wrl#HeadsUpDisplay","
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay
"],
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.
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.
- Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D Architecture
4.1
- https://mantis.web3d.org/view.php?id=1470
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.
Have fun with well-documented X3D extensibility! 😀👍
all the best, Don
On Thu, Aug 21, 2025 at 5:20 AM Holger Seelig via x3d-public <
x3d-public at web3d.org> wrote:
> 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.
>
> 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.
>
> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement
>
>
> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement
>
> Best regards,
> Holger
>
> —
> Holger Seelig
> Leipzig, Germany
>
> holger.seelig at yahoo.de
> https://create3000.github.io/x_ite/
> https://patreon.com/X_ITE
>
>
>
> Am 21.08.2025 um 12:42 schrieb Michalis Kamburelis via x3d-public <
> x3d-public at web3d.org>:
>
> Thank you -- but that's not yet enough :)
>
> The fact that appinfo is SFString says what information it can carry
> (OK, 1 string), but not yet how it's encoded. If "appinfo" would be a
> regular field inside a regular X3D node, it would be all we need...
> alas, it is not.
>
> As it stands, "appinfo" is part of "ProtoDeclare" and "field" in
> prototype interface -- these are special concepts with special syntax,
> in both X3D XML and classic encodings.
>
> - For the X3D 3.3 classic encoding, this is the relevant section:
>
> https://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/concepts.html#PROTOStatementSyntax
>
> - For the X3D 3.3 XML encoding, this is the relevant section:
>
> https://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/concepts.html#PrototypeAndFieldDeclarationSyntax
>
> I think we need "X3D 4.0 classic encoding" and "X3D 4.0 XML encoding"
> specs and they should extend above sections to include how the
> additional X3D 4.0 information ("appinfo", "documentation") is
> encoded.
>
> The XML encoding is kind of obvious in this case (as "ProtoDeclare"
> and "field" are XML elements, so "appinfo" and "documentation" can be
> just XML attributes), so it's not a big question. But classic encoding
> of them is really unknown, at least to me :)
>
> Regards,
> Michalis
>
> wt., 19 sie 2025 o 18:59 John Carlson via x3d-public
> <x3d-public at web3d.org> napisał(a):
>
>
> 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?
>
> John
>
> On Tue, Aug 19, 2025 at 11:17 AM John Carlson <yottzumm at gmail.com> wrote:
>
>
> Sorry, I the previous message contained 2 large images.
>
> The direct links are:
>
> https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare.appinfo
>
>
> https://www.web3d.org/x3d/content/X3dTooltips.html#field.appinfo
>
> John
>
> ---------- Forwarded message ---------
> From: John Carlson <yottzumm at gmail.com>
> Date: Tue, Aug 19, 2025 at 10:54 AM
> Subject: Re: [x3d-public] appinfo attribute/field
> To: Michalis Kamburelis <michalis.kambi at gmail.com>
> CC: Extensible 3D (X3D) Graphics public discussion <x3d-public at web3d.org>
>
>
> Michalis:
>
> 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.
>
> Thanks,
>
> John
>
>
> On Tue, Aug 19, 2025 at 10:46 AM Michalis Kamburelis <
> michalis.kambi at gmail.com> wrote:
>
>
> Let me add another question to this thread: Where is the specification
> of how to *encode* appinfo information in the X3D classic encoding?
>
> To add some background/context to this question:
>
> - Thanks to John pointing out in
> https://github.com/castle-engine/castle-engine/issues/688 , in CGE we
> lack support for "appinfo" attribute in ProtoDeclare / field.
>
> - I found a mention of new "appinfo" and "documentation" in the
> abstract X3D 4.0 spec:
>
> https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics
> ,"""Prototype and field declarations may optionally include appinfo
> functional descriptions (i.e., tooltip summary) and a documentation
> url providing a link to further related information."""
>
> - However, as the above is the "abstract" part of the spec ("X3D
> Abstract : Architecture and base components") so it naturally doesn't
> say how these "appinfo" and "documentation" are actually encoded. The
> official XML encoding and classic encoding specs are now at 3.3
> version -- so they don't mention how to encode this new X3D 4.0
> feature.
>
> - For XML encoding, it seems straightforward, judging from the
> testcase in https://github.com/castle-engine/castle-engine/issues/688
> . They are just XML attributes.
>
> <ProtoDeclare appinfo='...' name='...' ...>
>
> <field appinfo='...' ...>'
>
> OK, so XML encoding is simple enough:)
>
> - We need to know how to encode this information in X3D classic, to
> enable lossless conversion between X3D encodings (classic, XML etc.).
>
> - If there is a spec, and/or a clear example of how to do this in X3D
> classic encoding, please point me to it :) Thank you!
>
> Regards,
> Michalis
>
>
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>
>
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>
>
> _______________________________________________
> 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/20250821/ea3fc137/attachment-0001.html>
More information about the x3d-public
mailing list