rdl.json

{
    "name": "rdl",
    "version": 3,
    "comment": "This defines the schema for a schema, the output of the RDL parser. This can be used to represent schemas in JSON, Protobuf, Avro, etc, from a single definition.",
    "types": [
        {
            "StringTypeDef": {
                "type": "String",
                "name": "Identifier",
                "comment": "All names need to be of this restricted string type",
                "pattern": "[a-zA-Z_]+[a-zA-Z_0-9]*"
            }
        },
        {
            "StringTypeDef": {
                "type": "String",
                "name": "NamespacedIdentifier",
                "comment": "A Namespace is a dotted compound name, using reverse domain name order (i.e. \"com.yahoo.auth\")",
                "pattern": "([a-zA-Z_]+[a-zA-Z_0-9]*)(\\.[a-zA-Z_]+[a-zA-Z_0-9])*"
            }
        },
        {
            "AliasTypeDef": {
                "type": "Identifier",
                "name": "TypeName",
                "comment": "The identifier for an already-defined type"
            }
        },
        {
            "AliasTypeDef": {
                "type": "NamespacedIdentifier",
                "name": "TypeRef",
                "comment": "A type reference can be a simple name, or also a namespaced name."
            }
        },
        {
            "EnumTypeDef": {
                "type": "Enum",
                "name": "BaseType",
                "elements": [
                    {
                        "symbol": "Bool"
                    },
                    {
                        "symbol": "Int8"
                    },
                    {
                        "symbol": "Int16"
                    },
                    {
                        "symbol": "Int32"
                    },
                    {
                        "symbol": "Int64"
                    },
                    {
                        "symbol": "Float32"
                    },
                    {
                        "symbol": "Float64"
                    },
                    {
                        "symbol": "Bytes"
                    },
                    {
                        "symbol": "String"
                    },
                    {
                        "symbol": "Timestamp"
                    },
                    {
                        "symbol": "Symbol"
                    },
                    {
                        "symbol": "UUID"
                    },
                    {
                        "symbol": "Array"
                    },
                    {
                        "symbol": "Map"
                    },
                    {
                        "symbol": "Struct"
                    },
                    {
                        "symbol": "Enum"
                    },
                    {
                        "symbol": "Union"
                    },
                    {
                        "symbol": "Any"
                    }
                ]
            }
        },
        {
            "StringTypeDef": {
                "type": "String",
                "name": "ExtendedAnnotation",
                "comment": "ExtendedAnnotation - parsed and preserved, but has no defined meaning in RDL. Such annotations must begin with \"x_\", and may have an associated string literal value (the value will be \"\" if the annotation is just a flag).",
                "pattern": "x_[a-zA-Z_0-9]*"
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "TypeDef",
                "comment": "TypeDef is the basic type definition.",
                "fields": [
                    {
                        "name": "type",
                        "type": "TypeRef",
                        "comment": "The type this type is derived from. For base types, it is the same as the name"
                    },
                    {
                        "name": "name",
                        "type": "TypeName",
                        "comment": "The name of the type"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The comment for the type"
                    },
                    {
                        "name": "annotations",
                        "type": "Map",
                        "optional": true,
                        "comment": "additional annotations starting with \"x_\"",
                        "items": "String",
                        "keys": "ExtendedAnnotation"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "AliasTypeDef",
                "comment": "AliasTypeDef is used for type definitions that add no additional attributes, and thus just create an alias",
                "fields": []
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "BytesTypeDef",
                "comment": "Bytes allow the restriction by fixed size, or min/max size.",
                "fields": [
                    {
                        "name": "size",
                        "type": "Int32",
                        "optional": true,
                        "comment": "Fixed size"
                    },
                    {
                        "name": "minSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "Min size"
                    },
                    {
                        "name": "maxSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "Max size"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "StringTypeDef",
                "comment": "Strings allow the restriction by regular expression pattern or by an explicit set of values. An optional maximum size may be asserted",
                "fields": [
                    {
                        "name": "pattern",
                        "type": "String",
                        "optional": true,
                        "comment": "A regular expression that must be matched. Mutually exclusive with values"
                    },
                    {
                        "name": "values",
                        "type": "Array",
                        "optional": true,
                        "comment": "A set of allowable values",
                        "items": "String"
                    },
                    {
                        "name": "minSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "Min size"
                    },
                    {
                        "name": "maxSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "Max size"
                    }
                ]
            }
        },
        {
            "UnionTypeDef": {
                "type": "Union",
                "name": "Number",
                "comment": "A numeric is any of the primitive numeric types",
                "variants": [
                    "Int8",
                    "Int16",
                    "Int32",
                    "Int64",
                    "Float32",
                    "Float64"
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "NumberTypeDef",
                "comment": "A number type definition allows the restriction of numeric values.",
                "fields": [
                    {
                        "name": "min",
                        "type": "Number",
                        "optional": true,
                        "comment": "Min value"
                    },
                    {
                        "name": "max",
                        "type": "Number",
                        "optional": true,
                        "comment": "Max value"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "ArrayTypeDef",
                "comment": "Array types can be restricted by item type and size",
                "fields": [
                    {
                        "name": "items",
                        "type": "TypeRef",
                        "default": "Any",
                        "comment": "The type of the items, default to any type"
                    },
                    {
                        "name": "size",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicate the fixed size."
                    },
                    {
                        "name": "minSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicate the min size"
                    },
                    {
                        "name": "maxSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicate the max size"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "MapTypeDef",
                "comment": "Map types can be restricted by key type, item type and size",
                "fields": [
                    {
                        "name": "keys",
                        "type": "TypeRef",
                        "default": "String",
                        "comment": "The type of the keys, default to String."
                    },
                    {
                        "name": "items",
                        "type": "TypeRef",
                        "default": "Any",
                        "comment": "The type of the items, default to Any type"
                    },
                    {
                        "name": "size",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicates the fixed size."
                    },
                    {
                        "name": "minSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicate the min size"
                    },
                    {
                        "name": "maxSize",
                        "type": "Int32",
                        "optional": true,
                        "comment": "If present, indicate the max size"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "StructFieldDef",
                "comment": "Each field in a struct_field_spec is defined by this type",
                "fields": [
                    {
                        "name": "name",
                        "type": "Identifier",
                        "comment": "The name of the field"
                    },
                    {
                        "name": "type",
                        "type": "TypeRef",
                        "comment": "The type of the field"
                    },
                    {
                        "name": "optional",
                        "type": "Bool",
                        "default": false,
                        "comment": "The field may be omitted even if specified"
                    },
                    {
                        "name": "default",
                        "type": "Any",
                        "optional": true,
                        "comment": "If field is absent, what default value should be assumed."
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The comment for the field"
                    },
                    {
                        "name": "items",
                        "type": "TypeRef",
                        "optional": true,
                        "comment": "For map or array fields, the type of the items"
                    },
                    {
                        "name": "keys",
                        "type": "TypeRef",
                        "optional": true,
                        "comment": "For map type fields, the type of the keys"
                    },
                    {
                        "name": "annotations",
                        "type": "Map",
                        "optional": true,
                        "comment": "additional annotations starting with \"x_\"",
                        "items": "String",
                        "keys": "ExtendedAnnotation"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "StructTypeDef",
                "comment": "A struct can restrict specific named fields to specific types. By default, any field not specified is allowed, and can be of any type. Specifying closed means only those fields explicitly",
                "fields": [
                    {
                        "name": "fields",
                        "type": "Array",
                        "comment": "The fields in this struct. By default, open Structs can have any fields in addition to these",
                        "items": "StructFieldDef"
                    },
                    {
                        "name": "closed",
                        "type": "Bool",
                        "default": false,
                        "comment": "indicates that only the specified fields are acceptable. Default is open (any fields)"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "EnumElementDef",
                "comment": "EnumElementDef defines one of the elements of an Enum",
                "fields": [
                    {
                        "name": "symbol",
                        "type": "Identifier",
                        "comment": "The identifier representing the value"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "the comment for the element"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "EnumTypeDef",
                "comment": "Define an enumerated type. Each value of the type is represented by a symbolic identifier.",
                "fields": [
                    {
                        "name": "elements",
                        "type": "Array",
                        "comment": "The enumeration of the possible elements",
                        "items": "EnumElementDef"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "TypeDef",
                "name": "UnionTypeDef",
                "comment": "Define a type as one of any other specified type.",
                "fields": [
                    {
                        "name": "variants",
                        "type": "Array",
                        "comment": "The type names of constituent types. Union types get expanded, this is a flat list",
                        "items": "TypeRef"
                    }
                ]
            }
        },
        {
            "UnionTypeDef": {
                "type": "Union",
                "name": "Type",
                "comment": "A Type can be specified by any of the above specialized Types, determined by the value of the the 'type' field",
                "variants": [
                    "BaseType",
                    "StructTypeDef",
                    "MapTypeDef",
                    "ArrayTypeDef",
                    "EnumTypeDef",
                    "UnionTypeDef",
                    "StringTypeDef",
                    "BytesTypeDef",
                    "NumberTypeDef",
                    "AliasTypeDef"
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "ResourceInput",
                "comment": "ResourceOutput defines input characteristics of a Resource",
                "fields": [
                    {
                        "name": "name",
                        "type": "Identifier",
                        "comment": "the formal name of the input"
                    },
                    {
                        "name": "type",
                        "type": "TypeRef",
                        "comment": "The type of the input"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The optional comment"
                    },
                    {
                        "name": "pathParam",
                        "type": "Bool",
                        "default": false,
                        "comment": "true of this input is a path parameter"
                    },
                    {
                        "name": "queryParam",
                        "type": "String",
                        "optional": true,
                        "comment": "if present, the name of the query param name"
                    },
                    {
                        "name": "header",
                        "type": "String",
                        "optional": true,
                        "comment": "If present, the name of the header the input is associated with"
                    },
                    {
                        "name": "pattern",
                        "type": "String",
                        "optional": true,
                        "comment": "If present, the pattern associated with the pathParam (i.e. wildcard path matches)"
                    },
                    {
                        "name": "default",
                        "type": "Any",
                        "optional": true,
                        "comment": "If present, the default value for optional params"
                    },
                    {
                        "name": "optional",
                        "type": "Bool",
                        "default": false,
                        "comment": "If present, indicates that the input is optional"
                    },
                    {
                        "name": "flag",
                        "type": "Bool",
                        "default": false,
                        "comment": "If present, indicates the queryparam is of flag style (no value)"
                    },
                    {
                        "name": "context",
                        "type": "String",
                        "optional": true,
                        "comment": "If present, indicates the parameter comes form the implementation context"
                    },
                    {
                        "name": "annotations",
                        "type": "Map",
                        "optional": true,
                        "comment": "additional annotations starting with \"x_\"",
                        "items": "String",
                        "keys": "ExtendedAnnotation"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "ResourceOutput",
                "comment": "ResourceOutput defines output characteristics of a Resource",
                "fields": [
                    {
                        "name": "name",
                        "type": "Identifier",
                        "comment": "the formal name of the output"
                    },
                    {
                        "name": "type",
                        "type": "TypeRef",
                        "comment": "The type of the output"
                    },
                    {
                        "name": "header",
                        "type": "String",
                        "comment": "the name of the header associated with this output"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The optional comment for the output"
                    },
                    {
                        "name": "optional",
                        "type": "Bool",
                        "default": false,
                        "comment": "If present, indicates that the output is optional (the server decides)"
                    },
                    {
                        "name": "annotations",
                        "type": "Map",
                        "optional": true,
                        "comment": "additional annotations starting with \"x_\"",
                        "items": "String",
                        "keys": "ExtendedAnnotation"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "ResourceAuth",
                "comment": "ResourceAuth defines authentication and authorization attributes of a resource. Presence of action, resource, or domain implies authentication; the authentication flag alone is required only when no authorization is done.",
                "fields": [
                    {
                        "name": "authenticate",
                        "type": "Bool",
                        "default": false,
                        "comment": "if present and true, then the requester must be authenticated"
                    },
                    {
                        "name": "action",
                        "type": "String",
                        "optional": true,
                        "comment": "the action to authorize access to. This forces authentication"
                    },
                    {
                        "name": "resource",
                        "type": "String",
                        "optional": true,
                        "comment": "the resource identity to authorize access to"
                    },
                    {
                        "name": "domain",
                        "type": "String",
                        "optional": true,
                        "comment": "if present, the alternate domain to check access to. This is rare."
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "ExceptionDef",
                "comment": "ExceptionDef describes the exception a symbolic response code maps to.",
                "fields": [
                    {
                        "name": "type",
                        "type": "String",
                        "comment": "The type of the exception"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "the optional comment for the exception"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "Resource",
                "comment": "A Resource of a REST service",
                "fields": [
                    {
                        "name": "type",
                        "type": "TypeRef",
                        "comment": "The type of the resource"
                    },
                    {
                        "name": "method",
                        "type": "String",
                        "comment": "The method for the action (typically GET, POST, etc for HTTP access)"
                    },
                    {
                        "name": "path",
                        "type": "String",
                        "comment": "The resource path template"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The optional comment"
                    },
                    {
                        "name": "inputs",
                        "type": "Array",
                        "optional": true,
                        "comment": "An Array named inputs",
                        "items": "ResourceInput"
                    },
                    {
                        "name": "outputs",
                        "type": "Array",
                        "optional": true,
                        "comment": "An Array of named outputs",
                        "items": "ResourceOutput"
                    },
                    {
                        "name": "auth",
                        "type": "ResourceAuth",
                        "optional": true,
                        "comment": "The optional authentication or authorization directive"
                    },
                    {
                        "name": "expected",
                        "type": "String",
                        "default": "OK",
                        "comment": "The expected symbolic response code"
                    },
                    {
                        "name": "alternatives",
                        "type": "Array",
                        "optional": true,
                        "comment": "The set of alternative but non-error response codes",
                        "items": "String"
                    },
                    {
                        "name": "exceptions",
                        "type": "Map",
                        "optional": true,
                        "comment": "A map of symbolic response code to Exception definitions",
                        "items": "ExceptionDef",
                        "keys": "String"
                    },
                    {
                        "name": "async",
                        "type": "Bool",
                        "optional": true,
                        "comment": "A hint to server implementations that this resource would be better implemented with async I/O"
                    },
                    {
                        "name": "annotations",
                        "type": "Map",
                        "optional": true,
                        "comment": "additional annotations starting with \"x_\"",
                        "items": "String",
                        "keys": "ExtendedAnnotation"
                    },
                    {
                        "name": "consumes",
                        "type": "Array",
                        "optional": true,
                        "comment": "Optional hint for resource acceptable input types",
                        "items": "String"
                    },
                    {
                        "name": "produces",
                        "type": "Array",
                        "optional": true,
                        "comment": "Optional hint for resource output content types",
                        "items": "String"
                    },
                    {
                        "name": "name",
                        "type": "Identifier",
                        "optional": true,
                        "comment": "The optional name of the resource"
                    }
                ]
            }
        },
        {
            "StructTypeDef": {
                "type": "Struct",
                "name": "Schema",
                "comment": "A Schema is a container for types and resources. It is self-contained (no external references). and is the output of the RDL parser.",
                "fields": [
                    {
                        "name": "namespace",
                        "type": "NamespacedIdentifier",
                        "optional": true,
                        "comment": "The namespace for the schema"
                    },
                    {
                        "name": "name",
                        "type": "Identifier",
                        "optional": true,
                        "comment": "The name of the schema"
                    },
                    {
                        "name": "version",
                        "type": "Int32",
                        "optional": true,
                        "comment": "The version of the schema"
                    },
                    {
                        "name": "comment",
                        "type": "String",
                        "optional": true,
                        "comment": "The comment for the entire schema"
                    },
                    {
                        "name": "types",
                        "type": "Array",
                        "optional": true,
                        "comment": "The types this schema defines.",
                        "items": "Type"
                    },
                    {
                        "name": "resources",
                        "type": "Array",
                        "optional": true,
                        "comment": "The resources for a service this schema defines",
                        "items": "Resource"
                    },
                    {
                        "name": "base",
                        "type": "String",
                        "optional": true,
                        "comment": "the base path for resources in the schema."
                    }
                ]
            }
        }
    ]
}