Liquid Studio: How to write a JSON schema $ref to another file

Question

I'm trying to refer to a JSON schema located in a different file using "$ref" with Liquid Studio 2017. Both the referring JSON schema and the referred JSON schema are located within the same directory.

I tried it using relative paths:

"$ref": "referredSchema.json/propertyName"

and using absolute paths:

"$ref": "file:///C:/JSON/referredSchema.json/propertyName"
"$ref": "file:///JSON/referredSchema.json/propertyName"
"$ref": "file:///JSON/referredSchema.json#/propertyName"

and a few other variations. None of them worked, I always get an error message "Invalid URI". Also the documentation only mentions that refs to other documents are possible without giving a reasonable example.

So I wonder, what the expected URI format would be.

Answer 1

You can reference schemas defined in the local file or external files using the $ref property.

The issue you have is the fragment part (the bit after the #). This references a schema within the definitions property on the root schema.

The following example should show how to do this for local files and external files

Main.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "ReferenceToLocalSchema": {
            "$ref": "#/definitions/LocalType"
        },
        "ReferenceToExternalSchema": {
            "$ref": "Common.json#/definitions/ExternalType"
        }
    },
    "definitions": {
        "LocalType": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "no-write": {
                    "type": "boolean",
                    "default": false
                }
            }
        }
    }
}

Common.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "additionalProperties": false,
    "definitions": {
        "ExternalType": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "src": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "minLength": 1
                    }
                }
            },
            "required": [
                "src"
            ]
        }
    }
}

Notice the reference to the local schema

"$ref": "#/definitions/LocalType"

and the remote schema

"$ref": "Common.json#/definitions/ExternalType"

I've shown this with a relative url, but it could be a fully qualified url

"$ref": "file:///Common.json#/definitions/ExternalType"

One thing to note. At the moment the list of possible options presented in the UI will only show the definitions that are defined in the local file. References to external files will have to be entered in the code view.

If you still have questions please add the schema to the question.