json-schema-for-humans icon indicating copy to clipboard operation
json-schema-for-humans copied to clipboard

Examples not correctly parsed to YAML if starting with list instead of a property

Open mr-ssi opened this issue 7 months ago • 1 comments

I use generate-schema-doc with the following config flags: generate-schema-doc --config description_safe_mode=null --config no-collapse_long_descriptions --config no-collapse_long_examples --**config examples_as_yaml** --config no-show_breadcrumbs --expand-buttons --copy-css --copy-js --no-link-to-reused-ref --config template_name=js_offline "$FILENAME" "$DOCU_FILENAME"

When I have examples, where I only have a list of objects in the base, like follows, it does not transform the data to YAML:

"examples": [
    [
        {"path": "web/.*", "reviewers": ["[email protected]", "[email protected]"]},
        {"path": "backend/.*", "reviewers": ["[email protected]", "[email protected]", "[email protected]"]}
    ]
]

This will be shown in the documentation as a JSON String: [{'path': 'web/.*', 'reviewers': ['[email protected]', '[email protected]']}, {'path': 'backend/.*', 'reviewers': ['[email protected]', '[email protected]', '[email protected]']}]

Expected outcome:

- path: web/.*
  reviewers:
  - [email protected]
  - [email protected]
- path: backend/.*
  reviewers:
  - [email protected]
  - [email protected]
  - [email protected]

As soon as I add a property at the beginning, like:

"examples": [
    [
        "developers": 
        [
            {"path": "web/.*", "reviewers": ["[email protected]", "[email protected]"]},
            {"path": "backend/.*", "reviewers": ["[email protected]", "[email protected]", "[email protected]"]}
        ]
    ]
]

it renders just fine to a YAML representation:

developers:
- path: web/.*
  reviewers:
  - [email protected]
  - [email protected]
- path: backend/.*
  reviewers:
  - [email protected]
  - [email protected]
  - [email protected]

Example JSON Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "path": {
                "type": "string",
                "pattern": "^(\\^)?[\\w\\W]*([\\$])?$"
            },
            "reviewers": {
                "type": "array",
                "items": {
                    "type": "string",
                    "format": "email"
                },
                "minItems": 1
            }
        },
        "required": ["path", "reviewers"],
        "additionalProperties": false,
        "examples": [
            [
                {"path": "web/.*", "reviewers": ["[email protected]", "[email protected]"]},
                {"path": "backend/.*", "reviewers": ["[email protected]", "[email protected]", "[email protected]"]}
            ]
        ]
    }
}

mr-ssi avatar Sep 04 '25 08:09 mr-ssi

As a workaround, I wrote the example entirely as a YAML formatted string:

"examples": 
    [
        "- path: .*\n  reviewers:\n    - [email protected]"
    ]

mr-ssi avatar Sep 04 '25 08:09 mr-ssi