[X3D-Ecosystem] JSON Schema documentation

[John Carlson]

Don,

Just like XML Schema has “keywords,” so does JSON schema.  But I know we
were able to put in:

"$comment": "SFFloat initializeOnly",

successfully, so I know we could put in properties similar to that.

Obviously, people have documented JSON schemas before, so I’m asking about
“standard” practices, such that I can convert JSON schema to documentation
without a lot of development work.  I’m pretty sure you do that on a
regular basis for XML, so you have a more confident approach.  If you build
a small prototype that works in one case, I would have more confidence that
such things could work on a larger scale.  I am reluctant to add extra
documentation to JSON schema for performance reasons.

John

On Fri, Oct 10, 2025 at 2:55 PM Don Brutzman <don.brutzman at gmail.com> wrote:

> John, the X3D XML Schema includes the same appinfo and documentation
> attributes that are found in X3DUOM.  Indeed they are generated from the
> same place.
>
>    - X3D SXML Schema x3d-4.0.xsd Documentation
>    -
>    https://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0.html
>    - select node, node type, or field to find appinfo/documentation
>    values for most cases
>
> So in our future work on X3D JSON Schema, I would expect to apply the same
> values.  It is the same X3D scene graph and architecture in each case.
>
> Additional documentation for X3DJSAIL Java and X3DPSAIL Python software
> builds is inserted using X3D Tooltips.
>
>    - Extensible 3D (X3D) 4.0 Tooltips
>    - X3D Tooltips provide authoring hints for each node and field found
>    in X3D Architecture version 4 International Specification (IS).
>    - https://www.web3d.org/x3d/content/X3dTooltips.html
>    - https://www.web3d.org/x3d/tooltips/x3d-4.0.profile.xml (source)
>
> all the best, Don
> --
> X3D Graphics, Maritime Robotics, Distributed Simulation
> Relative Motion Consulting  https://RelativeMotion.info
>
>
> On Thu, Oct 9, 2025 at 9:42 PM John Carlson via X3D-Ecosystem <
> x3d-ecosystem at web3d.org> wrote:
>
>> Apparently, JSON schema has a “description” property for describing
>> schema objects.
>>
>> My question is, would it be best to place appinfo or documentation
>> attributes from X3DUOM in schema objects (schema properties, for example)?
>> Or some other combination?
>>
>> Some samples of documented schemas.
>>
>>
>> https://github.com/Clemens-U/jsonbuddy/tree/main/JSON%20Schema%20Documentation%20samples
>> <https://github.com/Clemens-U/jsonbuddy/tree/main>
>>
>> My thought is to create a “no-use” schema for documentation purposes, and
>> a performance schema for downloads and processing.
>>
>> What do people in general about these approaches?
>>
>> John
>>
>> --
>> X3D-Ecosystem mailing list
>> X3D-Ecosystem at web3d.org
>> http://web3d.org/mailman/listinfo/x3d-ecosystem_web3d.org
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-ecosystem_web3d.org/attachments/20251010/68d29346/attachment.html>