rdl.rdl

//
// 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.
//
name rdl;
version 3;

//
// All names need to be of this restricted string type
//
type Identifier String (pattern="[a-zA-Z_]+[a-zA-Z_0-9]*");

// A Namespace is a dotted compound name, using reverse domain name order (i.e. "com.yahoo.auth")
type NamespacedIdentifier String (pattern="([a-zA-Z_]+[a-zA-Z_0-9]*)(\\.[a-zA-Z_]+[a-zA-Z_0-9])*");


//
// The identifier for an already-defined type
//
type TypeName Identifier;

//
// A type reference can be a simple name, or also a namespaced name.
//
type TypeRef NamespacedIdentifier;

type BaseType Enum {
     Bool,
     Int8,
     Int16,
     Int32,
     Int64,
     Float32,
     Float64,
     Bytes,
     String,
     Timestamp,
     Symbol,
     UUID,
     Array,
     Map,
     Struct,
     Enum,
     Union,
     Any
}

//
// 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).
//
type ExtendedAnnotation String (pattern="x_[a-zA-Z_0-9]*");

//
// TypeDef is the basic type definition.
//
type TypeDef Struct {
    TypeRef type; // The type this type is derived from. For base types, it is the same as the name
    TypeName name; // The name of the type
    String comment (optional); // The comment for the type
	Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}

//
// AliasTypeDef is used for type definitions that add no additional attributes, and thus just create an alias
//
type AliasTypeDef TypeDef {
}

//
// Bytes allow the restriction by fixed size, or min/max size.
//
type BytesTypeDef TypeDef {
    Int32 size (optional); // Fixed size
    Int32 minSize (optional); // Min size
    Int32 maxSize (optional); // Max size
}

//
// Strings allow the restriction by regular expression pattern or 
// by an explicit set of values. An optional maximum size may be
// asserted
//
type StringTypeDef TypeDef {
    String pattern (optional); // A regular expression that must be matched. Mutually exclusive with values
    Array<String> values (optional); // A set of allowable values
    Int32 minSize (optional); // Min size
    Int32 maxSize (optional); // Max size
}

//
// A numeric is any of the primitive numeric types
//
type Number Union<Int8,Int16,Int32,Int64,Float32,Float64>;

//
// A number type definition allows the restriction of numeric values.
//
type NumberTypeDef TypeDef {
    Number min (optional); // Min value
    Number max (optional); // Max value
}

//
// Array types can be restricted by item type and size
//
type ArrayTypeDef TypeDef {
    TypeRef items (default="Any"); // The type of the items, default to any type
    Int32 size (optional); // If present, indicate the fixed size.
    Int32 minSize (optional); // If present, indicate the min size
    Int32 maxSize (optional); // If present, indicate the max size
}

//
// Map types can be restricted by key type, item type and size
//
type MapTypeDef TypeDef {
    TypeRef keys (default="String"); // The type of the keys, default to String.
    TypeRef items (default="Any"); // The type of the items, default to Any type
    Int32 size (optional); // If present, indicates the fixed size.
    Int32 minSize (optional); // If present, indicate the min size
    Int32 maxSize (optional); // If present, indicate the max size
}

//
//Each field in a struct_field_spec is defined by this type
//
type StructFieldDef Struct {
    Identifier name; // The name of the field
    TypeRef type; // The type of the field
    Bool optional (default=false); // The field may be omitted even if specified
    Any default (optional); // If field is absent, what default value should be assumed.
    String comment (optional); // The comment for the field
    TypeRef items (optional); // For map or array fields, the type of the items
    TypeRef keys (optional); // For map type fields, the type of the keys
    Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}

//
// 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
//
type StructTypeDef TypeDef {
    Array<StructFieldDef> fields; // The fields in this struct. By default, open Structs can have any fields in addition to these
    Bool closed (default=false); //indicates that only the specified fields are acceptable. Default is open (any fields)
}

//
// EnumElementDef defines one of the elements of an Enum
//
type EnumElementDef Struct {
     Identifier symbol; // The identifier representing the value
     String comment (optional); //the comment for the element
     Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}

//
// Define an enumerated type. Each value of the type is represented by a symbolic identifier.
//
type EnumTypeDef TypeDef {
     Array<EnumElementDef> elements; // The enumeration of the possible elements
}

//
// Define a type as one of any other specified type. 
//
type UnionTypeDef TypeDef {
     Array<TypeRef> variants; // The type names of constituent types. Union types get expanded, this is a flat list
}

//
// A Type can be specified by any of the above specialized Types, determined by the value of the the 'type' field
//
type Type Union<BaseType,StructTypeDef,MapTypeDef,ArrayTypeDef,EnumTypeDef,UnionTypeDef,StringTypeDef,BytesTypeDef,NumberTypeDef,AliasTypeDef>;

//
// ResourceOutput defines input characteristics of a Resource
//
type ResourceInput Struct {
    Identifier name; //the formal name of the input
    TypeRef type; //The type of the input
    String comment (optional); // The optional comment
    Bool pathParam (default=false); // true of this input is a path parameter
    String queryParam (optional); // if present, the name of the query param name
    String header (optional); // If present, the name of the header the input is associated with
    String pattern (optional); // If present, the pattern associated with the pathParam (i.e. wildcard path matches)
    Any default (optional); // If present, the default value for optional params
    Bool optional (default=false); // If present, indicates that the input is optional
    Bool flag (default=false); // If present, indicates the queryparam is of flag style (no value)
    String context (optional); // If present, indicates the parameter comes form the implementation context
    Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}

//
// ResourceOutput defines output characteristics of a Resource
//
type ResourceOutput Struct {
    Identifier name; //the formal name of the output
    TypeRef type; // The type of the output
    String header; // the name of the header associated with this output
    String comment (optional); // The optional comment for the output
    Bool optional (default=false); // If present, indicates that the output is optional (the server decides)
    Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}

//
// 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.
//
type ResourceAuth Struct {
     Bool authenticate (default=false); //if present and true, then the requester must be authenticated
     String action (optional); // the action to authorize access to. This forces authentication
     String resource (optional); // the resource identity to authorize access to
     String domain (optional); // if present, the alternate domain to check access to. This is rare.
}

//
// ExceptionDef describes the exception a symbolic response code maps to.
//
type ExceptionDef Struct {
     String type; // The type of the exception
     String comment (optional); //the optional comment for the exception
}

//
// A Resource of a REST service
//
type Resource Struct {
    TypeRef type; // The type of the resource
    String method; // The method for the action (typically GET, POST, etc for HTTP access)
    String path; // The resource path template
    String comment (optional); // The optional comment
    Array<ResourceInput> inputs (optional); // An Array named inputs
    Array<ResourceOutput> outputs (optional); // An Array of named outputs
    ResourceAuth auth (optional); // The optional authentication or authorization directive
    String expected (default="OK"); // The expected symbolic response code
    Array<String> alternatives (optional); // The set of alternative but non-error response codes
    Map<String,ExceptionDef> exceptions (optional); // A map of symbolic response code to Exception definitions
    Bool async (optional); //A hint to server implementations that this resource would be better implemented with async I/O
    Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
    Array<String> consumes (optional); // Optional hint for resource acceptable input types
    Array<String> produces (optional); // Optional hint for resource output content types
    Identifier name (optional); // The optional name of the resource
}

//
// A Schema is a container for types and resources. It is self-contained (no external references).
// and is the output of the RDL parser.
//
type Schema Struct {
    NamespacedIdentifier namespace (optional); // The namespace for the schema
    Identifier name (optional); // The name of the schema
    Int32 version (optional); // The version of the schema
    String comment (optional); // The comment for the entire schema
    Array<Type> types (optional); // The types this schema defines.
    Array<Resource> resources (optional); // The resources for a service this schema defines
    String base (optional); //the base path for resources in the schema.
    Map<ExtendedAnnotation,String> annotations (optional); //additional annotations starting with "x_"
}