How to automatically include all schemas in the source folder

[leonardopsantos]

Sorry for the neophyte question, but I have a somewhat complex JSON schema structure where a top-level schema includes several other schemas, which in turn define new objects in their $defs sections.

Say that I have two schema files:

my_schema.json:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "file:my_schema.json",
    "title": "My own JSON schema",
    "description": "A schema",
    "type": "object",
    "properties": {
        "name": {
            "description": "My name",
            "type": "string"
        },
        "foo": {
            "description": "A foo object",
            "type": "array",
            "items": {
                "$ref": "FooObject.json"
            },
            "minItems": 1
        }
    }
}

FooObject.json:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "file:FooObject.json",
    "title": "Foo object JSON schema",
    "description": "A schema",
    "type": "object",
    "properties": {
        "name": {
            "description": "Foo",
            "type": "string"
        },
        "bar": {
            "description": "Bar object",
            "type": "array",
            "items": {
                "$ref": "#/$defs/BarObject"
            },
            "minItems": 1
        }
    },
    "$defs": {
        "BarObject": {
            "type": "object",
            "properties": {
                "bar": {
                    "description": "Bar",
                    "type": "integer"
                }
            }
        }
    }
}

To include both files, I added to index.rst file:

JSON Schemas Documentation
==========================

.. jsonschema:: my_schema.json
.. jsonschema:: FooObject.json

Individually listing all objects is cumbersome as I have several files and it's bound to break when a new schema file is created.

What I would like is a directive like .. toctree:: that would be replaced by all schemas that were parsed.

Thanks!

[lnoor]

No need to apologize as long as you're not asking for money. (Then apologies won't help).

As to the subject. The thing is that this software was written to specifically solve my problem at the time. Which is different from yours now.

I believe .. toctree:: is not the best example since it requires you to enumerate all .rst files just as you are doing now with multiple ..jsonschema:: directives. So the only difference is the number of directives you need. What would be helpful for you is the ability to use wildcards, like so: .. jsonschema:: schemas/*.json. But I'm not going to build that.

I do have a different solution for you and that is to make use of the documentation build chain. Depending on your platform you either create your documentation using the make command or by executing a batch script. What you can do is to generate your index.rst file so that it will update the list of .. jsonschema:: directives with each run.

If you need help setting that up I might be able to help out if you are building on Linux. I do not use or own Windows or Apple computers so I can't help with those platforms.

[leonardopsantos]

@lnoor, thanks for the quick answer.

What would be helpful for you is the ability to use wildcards, like so: .. jsonschema:: schemas/*.json.

That would be useful indeed.

But I'm not going to build that.

That's OK. Can I submit a PR doing that?

Thanks!

[lnoor]

Absolutely! But that is not a promise it will be included. You're also welcome to propose a solution before putting in too much time.

I think it isn't quite that easy so I am curious to your solution. Do consider the json path suffix and the directive's options in your solution as well as properly passing the filenames for error reporting.

One route that I can think of at the moment is having from_file() and friends return an array of tuples. But that is only part of the solution.