CesiumGS / wetzel

Generate Markdown documentation from JSON Schema
Apache License 2.0
134 stars 54 forks source link

Definitions cannot refer to other definitions #73

Open javagl opened 2 years ago

javagl commented 2 years ago

Here is an example schema that refers to a type exampleReferenceDefinition that is defined in another file:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title" : "Definitions user example",
    "description" : "An example that uses definitions from another file",
    "type" : "object",
    "properties": {
        "exampleProperty": {
            "allOf": [
                {
                    "$ref": "definitions.schema.json#/definitions/exampleReferenceDefinition"
                }
            ]
        }
    }
}

The definitions.schema.json looks as follows:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title" : "Definitions example",
    "description" : "An example with definitions",
    "type" : "object",
    "definitions": {
        "exampleDefinition": {
            "title": "An example definition",
            "type": "string"
        },
        "exampleReferenceDefinition": {
            "title": "An example definition that refers to another one",
            "allOf": [
                {
                    "$ref": "#/definitions/exampleDefinition"
                }
            ]
        }
    }
}

This causes wezel to bail out:

C:\wetzel\lib\replaceRef.js:54
            throw new Error(`Unable to find $ref ${ref}`);
            ^

Error: Unable to find $ref #/definitions/exampleDefinition
    at replaceRef (C:\wetzel\lib\replaceRef.js:54:19)
    at replaceRef (C:\wetzel\lib\replaceRef.js:100:32)
...

Roughly: The definitions are not properly transported through the recursive calls of replaceRef.

My gut feeling is that this is related to https://github.com/CesiumGS/wetzel/issues/56 . More generally: The replaceRef approach of trying to completely "inline" the references may not be the most sustainable here. It does/will also cause trouble when/if allOf is replaced with $ref.

I've spent a few hours debugging the surroundings of replaceRef. Maybe I'll try to refactor this in an attempt to kill a few bugs with one stone, but it's hard to make promises here...

JC3 commented 2 years ago

This still appears to be an issue.

javagl commented 2 years ago

There haven't been any actual changes since this issue was reported. I tried to apply wetzel to another project, and stumbled over this and several other issues, and created a set of smaller changes to address them, but eventually, it did not appear to make sense to try and tackle these individually, so I created a branch with a larger refactoring at https://github.com/CesiumGS/wetzel/tree/generate-3dtiles (although I don't know for sure whether this really is an 'improvement', or just a 'change' ...)

I'll have a closer look at https://github.com/CesiumGS/wetzel/issues/81 and try to respond there a bit later today.