$ref to other files

[ajoga]

As I have multiple object loosely related to each other that are referencing common definitions, I'm exploring using $ref and referencing another file.

I'm getting weird outputs from jsonschema2md2, could this usage not be supported?

I've tried to render the schemas from this tutorial ; I named the files entry-schema.json and fstab.json. Rendered fstab.md yields:

# JSON Schema

## Pattern Properties

- **`^(/[^/]+)+$`**: Refer to *[https://example.com/entry-schema](#tps://example.com/entry-schema)*.
## Properties

- **`/`**: Refer to *[https://example.com/entry-schema](#tps://example.com/entry-schema)*.

I have two questions:

• Am I trying to be overkill referencing objects across files? Is this uncommon in practice?
• If this is unsupported, what would it take to be supported?

[khoa1160]

I'm experiencing the same issue. I think this line might be the culprit with [2:].

[bpleonardo]

@sbrunner I would like to implement this, but do you have any idea how you want this to render? Should it render each schema as separate files and point relative likes to each other or should it just be one giant file with all the schemas?

If the latter, how would this be implemented? Could we just concatenate the result of parse_schema for every schema (updating the anchors of course)?

[reteps]

I would think that you can specify at a schema level, whether it is external or not. It shouldn't matter that the original input came from 1 file or 3 -- in some scenarios, you may want it to output 5 md files, and in others, you want it to output a single file. A mapping between schema name and if it is external would be super cool.

[sbrunner]

For me, the priority is to have separate files.

[bpleonardo]

Ok. I'm thinking this:

1. We take an option on the CLI representing the base url (e.g. --base "https://example.com/schemas/") and we still take the root file.
2. In parse_schema we get any references to $refs pointing to files starting with base (https://example.com/schemas/file.schema.json) and store them for later. We don't do any modifications to the display of $ref (keep Refer to: [url]), still parsing local references.
3. After parsing the schema, we go through each stored reference and look for files named link.removeprefix(base) alongside the root file.
4. We call parse_schema for each of those files and save them at [stripped-id].md.

[bpleonardo]

For example, if we have a root file referencing https://example.com/filesystem.json, https://example.com/data.json and https://anotherexample.com/external.json, and call:

# $ ls
# root.json
# filesystem.json
# data.json

$ jsonschema2md --base "https://example.com/" root.json out.md

We get

$ ls
# root.json
out.md
# filesystem.json
filesystem.md
# data.json
data.md

[bpleonardo]

What do you think? We could add an option to make the references relative, so the refs would point to ./filesystem.json for example. Also if we find a reference that matches base and doesn't exist, we should raise an error.

[bpleonardo]

Now I'm thinking how to translate the URL. Should we just replace ".json" with "" and add an .md to the end? test.json#defs/3 -> test.md#defs/3?

[bpleonardo]

In addition to the above we could allow the definition of a map between schema IDs (everything after base_url excluding hash) and output files

[sbrunner]

+1 for relative path. We should also be careful to not create loops, careful also when we have different files but with the same name.

[bpleonardo]

What do you mean? If you mean cyclic loops it should be easy to avoid, just keep a reference of already parsed files.

About the files, I'm thinking we would keep the MD files relative to its schemas, that way the filesystem would already prevent duplicates, right?

[bpleonardo]

But we should prevent the user from pointing two schemas to the same file (if we add mapping)