docs-schema-draft.json

{
    "description" : "A schema describing API docs. Top-level object is the top level anonymous namespace",
    "extends" : [ { "$ref" : "#.defs.namespace" } ],
    "properties" : {
        "typedefs" : {
            "type" : "object",
            "optional" : true,
            "additionalProperties" : { "$ref" : "#.defs.typedef" }
        }
    },
    "defs" : {
        "named" : {
            "description" : "A thing that is named (e.g. namespace, class, method)",
            "properties" : {
                "name" : {
                    "type" : "string"
                }
            }        
        }, 
        "container" : {
            "description" : "A container of things that can be contained anywhere (functions, properties, etc.)",
            "properties" : {
                "classes" : {
                    "description" : "An object containing named classes keyed by name",
                    "type" : "object",
                    "additionalProperties" : { "$ref" : "#.defs.namedClass" },
                    "optional" : true            
                },
                "functions" : {
                    "type" : "array",
                    "optional" : true,
                    "items" : { "$ref" : "#.defs.namedCallable" }
                },
                "properties" : {
                    "type" : "array",
                    "optional" : true,
                    "items" : { "$ref" : "#.defs.namedValue" }
                }
            }
        },
        "typedef" : {
            "description" : "A named type.",
            "extends" : [
                { "$ref" : "$.defs.named" }
            ]
        },
        "namespace" : {
            "description" : "A namespace (named or anonymous - e.g. the global namespace)",
            "extends" : [ { "$ref" : "#.defs.container" } ],
            "properties" : {
                "namespaces" : {
                    "type" : "object",
                    "additionalProperties" : { "$ref" : "#.defs.namedNamespace" },
                    "optional" : true
                }
            }
        },
        "namedNamespace" : {
            "descripion" : "A named namespace (e.g. a namespace in a named hierarchy)",
            "extends" : [
                { "$ref" : "$.defs.named" },
                { "$ref" : "$.defs.namespace" }
            ]
        },
        "class" : {
            "description" : "A class (named or anonymous)",
            "extends" : [ { "$ref" : "#.defs.container" } ],
            "properties" : {
                "constructor" : {
                    "type" : [ { "$ref" : "#defs.callabale" } ],
                    "optional" : true
                },
                "methods" : {
                    "type" : "object",
                    "additionalProperties" : { "$ref" : "#.defs.namedCallable" },
                    "optional" : true
                }
            }
        },
        "namedClass" : {
            "description" : "A named class",
            "extends" : [
                { "$ref" : "#.defs.named" },
                { "$ref" : "#.defs.class" }
            ]
        },
        "callable" : {
            "description" : "A method, function, subroutine, etc.",
            "extends" : [ { "$ref" : "#.defs.named" } ],
            "properties" : {
                "description" : {
                    "type" : "string",
                    "optional" : true
                },
                "signatures" : {
                    "type" : "array",
                    "items" : { "$ref" : "#.defs.signature" }
                }
            }
        },
        "signature" : {
            "description" : "An interface to a function (can be overloaded)",
            "type" : "object",
            "properties" : {
                "name" : {
                    "type" : "string",
                    "optional" : true
                },
                "description" : {
                    "type" : "string",
                    "optional" : true
                },
                "example" : {
                    "type" : "string",
                    "optional" : true
                },
                "parameters" : {
                    "type" : "array",
                    "optional" : true,
                    "items" : { "$ref" : "#.defs.namedValue" }
                },
                "returns" : {
                    "type" : [ { "$ref" : "#.defs.value" } ],
                    "optional" : true
                }
            }
        },
        "value" : {
            "description" : "A value (e.g. parameter, returned value, etc.)",
            "properties" : {
                "type" : {
                    "type" : [ { "$ref" : "#.defs.types" } ],
                    "optional" : true
                },
                "description" : {
                    "type" : "string",
                    "optional" : "true"
                },
                "properties" : {
                    "type" : "object",
                    "additionalProperties" : { "$ref" : "#.defs.namedValue" }
                },
                "items" : { "$ref" : "#.defs.namedValue" }
            }
        },
        "namedValue" : {
            "description" : "A named value (e.g. function parameter)",
            "type" : "object",
            "extends" : [
                { "$ref" : "#.defs.named" },
                { "$ref" : "#.defs.value" }
            ],
            "additionalProperties" : {
                "default" : {
                    "optional" : true,
                    "type" : "string" 
                },
                "optional" :  {
                    "optional" : true,
                    "type" : "boolean"
                }
            }
        },
        "types" : {
            "description" : "A type or union of possible types (e.g. return types, parameter types, etc.)",
            "type" : [
                { "$ref" : "#.defs.type" },
                { "$ref" : "#.defs.typeUnion" }
            ]
        },
        "type" : {
            "description" : "A type (e.g. string, boolean, MyClass, options object, etc.)",
            "type" : "string"
        },
        "object" : {
            "description" : "...",
            "type" : "object",
            "additionalProperties" : { "$ref" : "#.namedValue" }
        },
        "typeUnion" : {
            "description" : "A set of types that a value can be",
            "type" : "array",
            "items" : { "$ref" : "#.defs.type" }
        }
    }
}