Improving JSON Schema Compatibility

[JBBianchi]

Currently, we use a combination of $ref and properties to inherit from internal definitions, as described in this JSON Schema blog post.

For example, each task inherits from taskBase, as shown in the set task:

 setTask: 
   type: object 
   $ref: '#/$defs/taskBase' 
   title: SetTask 
   description: A task used to set data. 
   required: [ set ] 
   unevaluatedProperties: false 
   properties: 
     set: 
       oneOf: 
         - type: object 
           minProperties: 1 
           additionalProperties: true 
         - type: string 
       title: SetTaskConfiguration 
       description: The data to set. 

I believe this approach relies on a feature introduced (or at least refined) in JSON Schema draft 2020-12. While this version is already a few years old, it is not yet widely supported by some tools. I have encountered compatibility issues in two different contexts:

• VS Code JSON validation regression microsoft/vscode-json-languageservice#260 (comment)
• json-schema-to-typescript $ref inheritance not supported bcherny/json-schema-to-typescript#613

A possible workaround would be to use allOf to inherit from a schema instead. For the set task, this would look like:

setTask:
   type: object 
   title: SetTask 
   description: A task used to set data. 
   required: [ set ] 
   unevaluatedProperties: false 
   allOf:
   - "$ref": "#/$defs/taskBase"
   - properties:
       set:
          oneOf: 
          - type: object 
            minProperties: 1 
            additionalProperties: true 
          - type: string 
          title: SetTaskConfiguration 
          description: The data to set. 

This change should not affect tools that already support the current approach but could improve compatibility—particularly with VS Code, which is required for draft PR.

Would this be an acceptable improvement for broader tool support? I'm curious to hear your thoughts!

[ricardozanini]

+1 to increase compatibility and not break the API. A nice 1.0.1 patch release.

[cdavernas]

Same here, even though we need to make thorough tests to ensure downcast will not break other schema features, which I'm afraid it will

[JBBianchi]

I created a branch with the modified schema (I also added a .json file to ease testing; it should be removed if/when we merge the branch):

https://github.com/neuroglia-io/serverless-workflow-specification/tree/fix-allof-inheritance/schema

Dear implementers, please let us know how this schema behaves for you.
cc @cdavernas @ricardozanini @fjtirado @matthias-pichler @geomagilles

[fjtirado]

@JBBianchi
Im afraid this change might be breaking the Java SDK. Reason is that the defauklt java generator tool itself was not supporting the schema, so I had to do a custom extension which deals with $ref, $oneOf and $anyOf. Now I will have to do the same with $oneOf embedded into $allOf, which is going to be tricky
Thats why I will prefer to not do the change unless is strictly required.
In any case, I need time to test the branch and improve the custom generator to cope with the new approach.

[geomagilles]

For me, I'm using the Java SDK to load the data structure. So I rely on @fjtirado point on view

[JBBianchi]

Thanks for the response! I completely understand that this change could make things trickier for the Java SDK, and I really appreciate the work you’ve put into making the generator handle $ref, $oneOf, and $anyOf.

That said, losing support for the VS Code extension would be a big drawback for the community, given how widely used VS Code is. Many users rely on it for schema validation and development, and ensuring compatibility could help lower the entry barrier for newcomers.

I definitely don’t want to introduce unnecessary breaking changes, so I appreciate you taking the time to test the branch and see what can be done. If there’s anything I can do to help with the process (testing, documentation, etc.), please let me know!

Looking forward to your thoughts.

[cdavernas]

That said, losing support for the VS Code extension would be a big drawback for the community

I totally agree, the VS Code extension is an absolute must have (even though I personally never used it)!
Therefore, I vote to perform the changes proposed by @JBBianchi

[fjtirado]

Ok, I need to make the generator work with the branched schema. Once I have this, we can merge both at the same time (to minimize the window in which the java generator does not work on main)