[x3d-public] appinfo attribute/field
John Carlson
yottzumm at gmail.com
Thu Aug 21 21:08:39 PDT 2025
Ok. I’ve done zero work on JSON schema. If you have a better term than X3D
JSON Schema, I’m all ears. It’s not only my work, Roy Walmsley gave me a
significant boost up, so I’d like to include him. I can credit him as
well. Without X3D JSON, there won’t be any X3D JSON Schema, so I can
credit you as well.
I gained inspiration for creating the mapping between X3DUOM and X3D JSON
Schema from you.
I’m perfectly okay with using X3D XML Schema with X3D JSON, as long as
there’s a web client based solution.
It’s not my personal work.
John
On Thu, Aug 21, 2025 at 6:05 PM Don Brutzman <don.brutzman at gmail.com> wrote:
> Appreciate your work on JSON schema John. If you share it further, please
> be sure to note that is your personal work.
>
> Am looking forward to continuing work with X3DUOM autogeneration and
> comprehensive unit testing using the X3D Example Archives, in tandem with
> X3D JSON File Encoding draft standard development. Likely such work can
> start after 30th Anniversary Web3D Conference this fall.
>
> Have fun with X3D JSON!
>
> all the best, Don
>
> --
> Don Brutzman
> X3D graphics, virtual worlds, Navy robotics
> https://faculty.nps.edu/brutzman
>
>
> On Thu, Aug 21, 2025 at 12:34 John Carlson <yottzumm at gmail.com> wrote:
>
>> I’ve also contacted the JSON Schema Slack site, and someone asked if they
>> could post our X3D JSON Schema, so the word is getting out.
>>
>> John
>> On Thu, Aug 21, 2025 at 1:54 PM John Carlson <yottzumm at gmail.com> wrote:
>>
>>> Great news about JSON, Don.
>>>
>>> To clarify:
>>>
>>>
>>> - *X3D JSON Encoding*
>>> - add 19776-5, implemented
>>> <https://www.web3d.org/x3d/stylesheets/X3dToJson.html>, needs JSON
>>> Schema <https://json-schema.org/learn/miscellaneous-examples> autogenerated
>>> by X3DUOM <https://www.web3d.org/specifications/X3DUOM.html>
>>>
>>>
>>> We have X3D JSON Schema generated by python from X3DUOM, and we have a
>>> way to validate X3D JSON against X3D XML Schema. If you want to generate
>>> the X3D JSON Schema yourself, great, we can compare notes. Last I heard,
>>> https://json-schema.org/specification was going to post their own
>>> standards, and also .glTF has a JSON schema. If we want an ISO standard,
>>> the JSON is already standardized, so since JSON Schema is JSON, JSON Schema
>>> is already standardized.
>>>
>>> I made a mapping from X3DUOM to X3D JSON schema here, which can be used
>>> to create a XSLT mapping, alternative licenses are possible:
>>> https://raw.githubusercontent.com/coderextreme/X3DJSONLD/refs/heads/master/src/main/python/index.html.
>>> Note that my X3D JSON schema includes the X_ITE component, and X_ITE
>>> probably isn’t covered in this document.
>>>
>>> I note that Aaron’s work needs to be validated against more than X_ITE
>>> and Sunrize before approval. We should make an effort to make sure his
>>> Rawkee work meets the standards.
>>>
>>> This means converting his X3D XML with the tools we have and testing
>>> conversions, and output from conversions.
>>>
>>> Pretty pictures aren’t the whole story.
>>>
>>> John
>>> On Thu, Aug 21, 2025 at 12:25 PM Don Brutzman via x3d-public <
>>> x3d-public at web3d.org> wrote:
>>>
>>>> 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
>>>>>
>>>> _______________________________________________
>>>> 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/c943cdd5/attachment-0001.html>
More information about the x3d-public
mailing list