Unknown type for array with anyOf items

[wayneashleyberry]

What did you do

jsonschema -d .

What did you expect to happen

An array type with multiple item types should be documented correctly, with links to each allowed type.

What happened

Unknown type.

What's your environment

• Operating System: macOS 10.14.1
• node.js version: 11.2.0

Do you have example files:

For this schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "items": {
            "type": "array",
            "items": {
                "anyOf": [
                    {
                        "$ref": "#/definitions/Thing"
                    },
                    {
                        "$ref": "#/definitions/OtherThing"
                    }
                ]
            }
        }
    },
    "definitions": {
        "Thing": {
            "properties": {}
        },
        "OtherThing": {
            "properties": {}
        }
    }
}

I'm getting following Markdown:

Array type: array
All items must be of the type:
Unknown type ``.

---

Test files and output can be found here: https://github.com/wayneashleyberry/jsonschema2md-issues/tree/master/array-of

[trieloff]

I suggest to turn "Thing or Other Thing" into a new schema and reference that. Documenting type structures of arbitrary depth is quite hard (especially in Markdown, where you have only limited ways of expressing nesting and structure), so this would make your Schema a bit more comprehensible.

[wayneashleyberry]

@trieloff what would a schema that could have many "sub-schema's" look like?

To try and make this clearer, the case I'm working with is an array of layers where a layer can be a text layer, image layer or shape layer. I started out with conditional validation on an enum but that soon got out of hand because the single "layer" schema was massive.

I now have a layer schema which each typed layer "inherits" and it's working really well. The only change I'd expect in the documentation is for "All items must be of the type: Unknown type ``." to read "All items must be of the type ImageLayer, `TextLayer` or `ShapeLayer`" if that makes sense?

[wayneashleyberry]

Here's a simplified example of the actual project I'm working on:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "Project",
    "properties": {
        "layers": {
            "type": "array",
            "minItems": 1,
            "items": {
                "oneOf": [
                    {
                        "$ref": "#/definitions/TextLayer"
                    },
                    {
                        "$ref": "#/definitions/ImageLayer"
                    },
                    {
                        "$ref": "#/definitions/ShapeLayer"
                    }
                ]
            }
        }
    },
    "definitions": {
        "ImageLayer": {
            "allOf": [
                {
                    "$ref": "#/definitions/Layer"
                }
            ],
            "properties": {
                "layerType": {
                    "const": "image"
                }
            }
        },
        "TextLayer": {
            "allOf": [
                {
                    "$ref": "#/definitions/Layer"
                }
            ],
            "properties": {
                "layerType": {
                    "const": "text"
                },
                "text": {
                    "type": "string",
                    "examples": [
                        "Hello, World!"
                    ]
                }
            },
            "required": [
                "text"
            ]
        },
        "ShapeLayer": {
            "allOf": [
                {
                    "$ref": "#/definitions/Layer"
                }
            ],
            "properties": {
                "layerType": {
                    "const": "shape"
                }
            }
        },
        "Layer": {
            "type": "object",
            "title": "Layer",
            "properties": {
                "layerType": {
                    "type": "string",
                    "enum": [
                        "text",
                        "image",
                        "shape"
                    ]
                },
                "opacity": {
                    "description": "This field represents the opacity of a layer, zero being completely transparent.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "examples": [
                        0.754
                    ]
                }
            },
            "required": [
                "layerType"
            ]
        }
    }
}

[trieloff]

"All items must be of the type: Unknown type ``." to read "All items must be of the type ImageLayer, TextLayer or `ShapeLayer`" if that makes sense?

Yes, that makes sense. For jsonschema2md only schemas that are in their own file (and built-in types) are treated as named types. This means if you move the definitions of Layer, ImageLayer, TextLayer, etc. into separate files, jsonschema2md can pick up the name, and create a nice documentation page for each schema. If you keep it as definitions inside a big schema, jsonschema2md will try to inline the documentation if it is not too deep, or just give up.

In XDM we have something quite similar with Image and Video, which both extend Asset:

• https://github.com/adobe/xdm/blob/master/docs/reference/assets/image.schema.md
• https://github.com/adobe/xdm/blob/master/docs/reference/assets/video.schema.md
• https://github.com/adobe/xdm/blob/master/docs/reference/assets/asset.schema.md

[trieloff]

🎉 This issue has been resolved in version 4.0.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[wayneashleyberry]

@trieloff I'm not seeing v4.0.0 on npm yet?

[trieloff]

@wayneashleyberry does this link work for you: https://www.npmjs.com/package/@adobe/jsonschema2md/v/4.0.0?

[wayneashleyberry]

Yeah, I see it now - thanks @trieloff