json-api-schema/json-api-schema.json

JSON Api Schema is a JSON dialect that can describe any Web Based API that uses JSON to exchange data.

{   
    "title": "JSON-DMA - JSON Data Model API description language",
    "description": "This schema allow to write machine-understandable descriptions of a Web API that uses JSON as data interchange format.",
    "id": "http://jsondma.com/schema",
    "$ref": "#/definitions/Api",

    "definitions": {
        "Api": {
            "title": "Api",
            "description": "The entry point of the model. An Api is a set of interactions, types and resources. An api exposes also protocol specific global informations to configure interactions.",
            "allOf": [
                { "$ref": "#/definitions/Documentable" },
                { "$ref": "#/definitions/HasProtocols" },
                {
                    "type": "object",
                    "properties": {
                        "version":   { "type": "string", "description": "This API Version" },
                        "actions":   { "$ref": "#/definitions/ActionMap" },
                        "events":    { "$ref": "#/definitions/EventMap" },
                        "resources": { "$ref": "#/definitions/ResourceMap" },
                        "types":     { "$ref": "#/definitions/TypeMap" },
                    }
                }
            ]
        },

        "Type": {
            "description": "Any data type. Type nodes have significance as long as they are referenced in a TypeMap, since they should have a name.",
            "allOf": [
                { "$ref": "#/definitions/Documentable" },
                {
                    "properties": {
                        "schema": { "$ref": "#/definitions/Schema" }
                    }
                }
            ]
        },

        "Resource": {
            "title": "Resource",
            "description": "A Resource maps Interactions with Types. A Resource can have nested resources.",
            "allOf": [
                { "$ref": "#/definitions/Documentable" },
                { "$ref": "#/definitions/HasProtocols" },
                {
                    "type": "object",
                    "properties": {
                        "type":      { "type": "string", "description": "The name of a Type declared in this model" },
                        "actions":   { "$ref": "#/definitions/ActionMap" },
                        "events":    { "$ref": "#/definitions/EventMap" },
                        "resources": { "$ref": "#/definitions/ResourceMap" }
                    },
                    "requiredProperties": [ "type" ]
                }
            ]
        },
        
        "Action": {
            "title": "Action",
            "description": "A basic client-side initiated interaction.",
            "allOf": [
                { "$ref": "#/definitions/Documentable" },
                { "$ref": "#/definitions/HasProtocols" },
                {
                    "type": "object",
                    "properties": {
                        "params":    { "$ref": "#/definitions/Schema" },
                        "returns":   { "$ref": "#/definitions/Schema" }
                    }
                }
            ]
        },

        "Event": {
            "title": "Event",
            "description": "A basic server-side initiated interaction.",
            "allOf": [
                { "$ref": "#/definitions/Documentable" },
                { "$ref": "#/definitions/HasProtocols" },
                {
                    "type": "object",
                    "properties": {
                        "params":    { "$ref": "#/definitions/Schema" }
                    }
                }
            ]
        },
        
        "Schema": {
            "allOf": [
                {
                    "$ref": "http://json-schema.org/draft-04/schema#"
                }
            ]
        },

        "Documentable": {
            "properties": {
                "title": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                }
            }
        },

        "HasProtocols": {
            "properties": {
                "protocols": {
                    "type": "object"
                }
            }
        },

        "ActionMap": {
            "description": "A mapping of actions to their names",
            "type": "object",
            "patternProperties": {
                "^[^ ]+$": { "$ref": "#/definitions/Action" }
            }
        },
        
        "EventMap": {
            "description": "A mapping of events to their names",
            "type": "object",
            "patternProperties": {
                "^[^ ]+$": { "$ref": "#/definitions/Event" }
            }
        },

        "ResourceMap": {
            "description": "A mapping of resources to their names",
            "type": "object",
            "patternProperties": {
                "^[^ ]+$": { "$ref": "#/definitions/Resource" }
            }
        },

        "TypeMap": {
            "description": "A mapping of types to their names",
            "type": "object",
            "patternProperties": {
                "^[^ ]+$": { "$ref": "#/definitions/Type" }
            }
        }
    }
}