-
Notifications
You must be signed in to change notification settings - Fork 4
/
rdl.rdl
261 lines (234 loc) · 10.1 KB
/
rdl.rdl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
//
// 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_"
}