[X3D-Ecosystem] Heads Up! ANNOUNCE: X3D JSON schema, breaking change

[John Carlson]

Apologies that this comes in the middle of the holidays!

Don, tread with care when applying the ProtoInstance.name being a required
change.

I don't plan to apply the change to x3dvalidate until the end of February
for those who are relying on it.  I still need to test changes in
X3DJSONLD.  This is an advance warning!

On Sun, Dec 29, 2024 at 8:05 AM John Carlson <yottzumm at gmail.com> wrote:

> Don, thanks for responding.
>
> 1.  I will try to make name required in ProtoInstance, pending your
> changes to validation.
>

Upon review, it looks like there are errors in not requiring @name in both
ProtoInstance subschemas of X3D JSON schema 4.0.  What I did was make
ProtoInstance's field /name/ have use="required" in X3DUOM, V4.0.  I don't
know what will happen with X3D 3.0-3.3 yet.  Initial changes
indicated that @name is required with nodes without @USE.  I made changes
to the python to accommodate the ProtoInstance @USE subschema, requiring
both @USE and @name for X3D V4.0.

Original X3D JSON schema 4.0:

  "ProtoInstance": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "@class": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@name": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@USE": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "-children": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "#comment": {
                    "type": "string",
                    "$comment": "#comment statements are the only allowed
in -children node when using a USE field"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "required": [
            "@USE"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "-children": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "#comment": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "fieldValue": {
              "$ref": "#/$defs/fieldValue"
            },
            "IS": {
              "$ref": "#/$defs/IS"
            },
            "-metadata": {
              "$ref": "#/$defs/-X3DMetadataObjectSFNode"
            },
            "@name": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@DEF": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@class": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@id": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@style": {
              "$comment": "SFString inputOutput",
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ]
    },

Here's the new result (Only for X3D V4.0, I will have to edit the python to
include other versions).  Note that @name is now *required* in all cases,
even if @USE is provided.


    "ProtoInstance": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "@class": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@name": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@USE": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "-children": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "#comment": {
                    "type": "string",
                    "$comment": "#comment statements are the only allowed
in -children node when using a USE field"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "required": [
            "@name",
            "@USE"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "-children": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "#comment": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "fieldValue": {
              "$ref": "#/$defs/fieldValue"
            },
            "IS": {
              "$ref": "#/$defs/IS"
            },
            "-metadata": {
              "$ref": "#/$defs/-X3DMetadataObjectSFNode"
            },
            "@name": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@DEF": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@class": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@id": {
              "$comment": "SFString inputOutput",
              "type": "string"
            },
            "@style": {
              "$comment": "SFString inputOutput",
              "type": "string"
            }
          },
          "required": [
            "@name"
          ],
          "additionalProperties": false
        }
      ]
    },

Since this change is a breaking change, and may invalidate some X3D JSON
files, I will wait an amount of time before I implement this change in my
repositories, realizing that I may need to check my code in due to a
service call on my machine.  I suggested *not* upgrading x3dvalidate and
X3DJSONLD until you've had a chance to test your JSON.

Thanks,

John

>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-ecosystem_web3d.org/attachments/20241229/803a3657/attachment.html>