JSON-Schema As Language Agnostic Interface Definition Format

example-plugin-schema.json

{
    "$schema": "./plugin-metaschema.json",
    "title": "A Plug-In",
    "description": "An example Plug-In for our core-application",
    "type": "object",
    "properties": {
        "id": {
            "type": "number",
            "title": "ID",
            "description": "Unique task number",
            "minimum": 1
        },
        "operation": {
            "title": "Operation",
            "type": "object",
            "description": "Operation to execute",
            "oneOf": [
                {
                    "properties": {
                        "name": {
                            "type": "string",
                            "const": "ping"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name"
                    ]
                },
                {
                    "properties": {
                        "name": {
                            "type": "string",
                            "const": "login"
                        },
                        "params": {
                            "type": "object",
                            "properties": {
                                "username": {
                                    "type": "string"
                                },
                                "password": {
                                    "type": "string"
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "username",
                                "password"
                            ]
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name",
                        "params"
                    ]
                },
                {
                    "properties": {
                        "name": {
                            "type": "string",
                            "const": "logout"
                        },
                        "params": {
                            "type": "object",
                            "properties": {
                                "session": {
                                    "type": "string"
                                },
                                "host": {
                                    "type": "string"
                                },
                                "cookie": {
                                    "type": "string"
                                },
                                "version": {
                                    "type": "string"
                                },
                                "timeout": {
                                    "type": "number"
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "session",
                                "host",
                                "cookie",
                                "version",
                                "timeout"
                            ]
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name",
                        "params"
                    ]
                }
            ],
            "required": [
                "name"
            ]
        }
    },
    "required": [
        "id",
        "operation"
    ],
    "definitions": {}
}

plugin-metaschema.json

{
    "$schema": "http://json-schema.org/draft-06/schema#",
	"title": "Plug-In Metaschema",
    "description": "All plug-ins for the core-application MUST be valid against this schema",
    "allOf": [
        {
            "$ref": "http://json-schema.org/draft-06/schema#"
        },
        {
            "properties": {
                "properties": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "object",
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "const": "number"
                                },
                                "title": {
                                    "type": "string",
                                    "const": "ID"
                                },
                                "description": {
                                    "type": "string",
                                    "const": "Unique task number"
                                },
                                "minimum": {
                                    "type": "number",
                                    "const": 1
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "type",
                                "title",
                                "description",
                                "minimum"
                            ]
                        },
                        "operation": {
                            "type": "object",
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "const": "object"
                                },
                                "title": {
                                    "type": "string",
                                    "const": "Operation"
                                },
                                "description": {
                                    "type": "string",
                                    "const": "Operation to execute"
                                },
                                "properties": {
                                    "$ref": "#/definitions/operation"
                                },
                                "oneOf": {
                                    "type": "array",
                                    "allOf": [
                                        {
                                            "items": [
                                                {
                                                    "$ref": "#/definitions/coreOperations"
                                                },
                                                {
                                                    "$ref": "#/definitions/operation"
                                                }
                                            ]
                                        }
                                    ],
                                    "additionalItems": false,
                                    "minimum": 1
                                },
                                "required": {
                                    "type": "array",
                                    "const": [
                                        "name"
                                    ]
                                }
                            },
                            "oneOf": [
                                {
                                    "required": [
                                        "type",
                                        "title",
                                        "description",
                                        "properties",
                                        "required"
                                    ]
                                },
                                {
                                    "required": [
                                        "type",
                                        "title",
                                        "description",
                                        "oneOf",
                                        "required"
                                    ]
                                }
                            ]
                        },
                        "required": {
                            "type": "array",
                            "const": [
                                "id",
                                "name"
                            ]
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "operation"
                    ]
                },
                "required": {
                    "type": "array",
                    "const": [
                        "id",
                        "operation"
                    ]
                }
            },
            "required": [
                "properties",
                "required"
            ]
        }
    ],
    "definitions": {
        "coreOperations": {
            "type": "object",
            "properties": {
                "properties": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "object",
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "const": "string"
                                },
                                "const": {
                                    "type": "string",
                                    "const": "ping"
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "type",
                                "const"
                            ]
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name"
                    ]
                },
                "additionalProperties": {
                    "type": "boolean",
                    "enum": [
                        false
                    ]
                },
                "required": {
                    "type": "array",
                    "const": [
                        "name"
                    ]
                }
            },
            "additionalProperties": false,
            "required": [
                "properties",
                "required",
                "additionalProperties"
            ]
        },
        "operation": {
            "type": "object",
            "properties": {
                "properties": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "object",
                            "title": "Operation Name",
                            "description": "Name of the operation to execute",
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "const": "string",
                                    "title": "Type",
                                    "description": "The type of the operation name (always string)"
                                },
                                "title": {
                                    "type": "string",
                                    "title": "Title",
                                    "description": "The title of this operation (optional)"
                                },
                                "description": {
                                    "type": "string",
                                    "title": "Description",
                                    "description": "The description of this operation (optional)"
                                },
                                "const": {
                                    "type": "string",
                                    "title": "Const",
                                    "description": "The value of the operation name (the actual name)"
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "type",
                                "const"
                            ]
                        },
                        "params": {
                            "type": "object",
                            "title": "Operation Parameters",
                            "description": "Parameters for the operation (optional)",
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "const": "object"
                                },
                                "properties": {
                                    "$ref": "#/definitions/param"
                                },
                                "additionalProperties": {
                                    "type": "boolean",
                                    "enum": [
                                        false
                                    ]
                                },
                                "required": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    },
                                    "additionalItems": false
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "type",
                                "properties",
                                "additionalProperties"
                            ]
                        }
                    },
                    "required": [
                        "name"
                    ]
                },
                "additionalProperties": {
                    "type": "boolean",
                    "enum": [
                        false
                    ]
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "additionalProperties": false,
            "required": [
                "properties",
                "additionalProperties"
            ]
        },
        "param": {
            "type": "object",
            "additionalProperties": {
                "type": "object",
                "properties": {
                    "type": {
                        "description": "The type of the operation parameter (only primitives)",
                        "type": "string",
                        "enum": [
                            "string",
                            "number",
                            "boolean"
                        ]
                    },
                    "title": {
                        "type": "string",
                        "title": "Title",
                        "description": "The title of this parameter (optional)"
                    },
                    "description": {
                        "type": "string",
                        "title": "Description",
                        "description": "The description of this parameter (optional)"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    }
}

plugin-specific-login-operations.json

{
    "$schema": "./example-plugin-schema.json",
    "id": 123456,
    "operation": {
        "name": "login",
        "params": {
            "username": "bob",
            "password": "passw0rd!"
        }
    }
}

plugin-specific-logout-operations.json

{
    "$schema": "./example-plugin-schema.json",
    "id": 123457,
    "operation": {
        "name": "logout",
        "params": {
            "session": "529ca7ab-d88b-32ab-2039-2b79d933c6e5",
            "host": "example.com",
            "cookie": "79dfca86849f9ddba026a3446",
            "version": "v5.1",
            "timeout": 1530963815
        }
    }
}

required-ping-operation.json

{
    "$schema": "./example-plugin-schema.json",
    "id": 1,
    "operation": {
        "name": "ping"
    }
}