[X3D-Ecosystem] JSON Schema documentation

[John Carlson]

For example, here’s some JSONBuddy documentation on the JSON schema Roy and
I created:

https://github.com/Clemens-U/jsonbuddy/blob/main/JSON%20Schema%20Documentation%20samples/x3d-4.0-JSONSchema.html

If you’re on your iPhone, I recommend the Share button instead of
downloading.

Maybe you already know that.

John

On Fri, Oct 10, 2025 at 10:35 PM John Carlson <yottzumm at gmail.com> wrote:

> 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/20251011/d41a473f/attachment.html>