4 * Copyright 2016 RIFT.IO Inc
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
23 * @file rw-pb-ext.yang
24 * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg
26 * @brief RiftWare yang to protobuf conversion extensions
31 namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext";
38 "RIFT yang extensions for converting yang files to Google
39 Protocol Buffers (protobuf) using rift protoc-c extensions.";
45 "Generate an equivalent, top-level, protobuf message for this
46 container, list, rpc input, rpc output, or notification. The
47 argument is the name of the protobuf message type. Allowed
48 values are valid C identifiers.
50 The protobuf definition will only be generated when processing
51 the same module that defines the yang object - a duplicate will
52 not be generated when importing reusing a yang object via uses,
53 or when importing the module.";
59 "Change the name of an embedded protobuf message type for this
60 container or list. Allowed values are valid C identifiers.
62 In lieu of this extension, embedded protobuf message typenames
63 are based on the fieldname, and further mangled by removing
64 underscores and CamelCased at underscore boundaries. This
65 extension allows the automatic mangling procedure to be
68 This extension is incompatible with msg-new, which already
69 defines the typename for top-level messages. Use this extension
70 solely for embedded messages.";
76 "Set the protobuf message rw_msgopts flat option on a container
77 or list statement. Allowed values are 'true', 'false', and
78 'auto'. The default is 'false' for top-level messages, and
79 'auto' for embedded messages. If 'auto' is specified, the
80 behavior is the same as the enclosing container or list.
82 Unless overridden, this extension effectively applies to all
83 enclosed descendent container and list statements. Flatness will
84 be required by the protobuf compilation step.";
87 extension msg-tag-base {
90 "Specify a base tag value for a container, list, grouping, or
91 uses statement. Field tags may be specified relative to this
92 base. Allowed values are positive
94 // ATTN: would really like to specify field-relative in uses!
98 extension msg-tag-reserve {
101 "Reserve space in the tag numbering for future expansion of the
102 enclosing grouping, container, or choice. Must be a positive
103 decimal integer. Choose carefully, as you cannot increase the
104 value at a later time.";
108 extension msg-proto-max-size {
111 "Specify the maximum size of this message in the C structure or
112 so in bytes. Allowed values are positive decimal integers.";
115 extension msg-typedef {
118 "Create a prototbuf-c message typedef for the original, base
119 definition of the container, list, grouping, rpc input, rpc
120 output, or notification. Allowed values are valid C identifiers.
122 typename will be appended to the mangeled protobuf package name
123 and an underscore, to ensure name uniqueness across the global
126 The typedef will only be generated when processing
127 the same module that defines the yang object - a duplicate will
128 not be generated when importing reusing a yang object via uses,
129 or when importing the module.";
132 extension field-name {
133 argument "fieldname";
135 "Change the name of the element to fieldname, when converting the
136 object to protobuf. Allowed values are valid C identifiers.
138 In lieu of this extension, element names will be used as-is, if
139 possible, or mangled to fit in the C identifier character space
140 (invalid C identifier characters will be replaced with
141 underscore). This extension allows the automatic mangling
142 procedure to be overridden.";
145 extension field-inline {
146 argument "selection";
148 "Set the protobuf field 'inline' option on a container, list,
149 leaf-list, or leaf statement. Allowed values are 'true',
150 'false', and 'auto'. If 'auto' is specified, the behavior is
151 controlled by the enclosing container or list's protobuf-msg-flat
154 When applied to a container or list statement, this extension is
155 inherited by all enclosed objects, unless overridden.";
158 extension field-inline-max {
161 "Set the protobuf field 'inline_max' option for list and
162 leaf-list statements. Allowed values are a positive decimal
163 integer, 'yang', or 'none'. Example limits:
169 If 'none' is specified, then the inline_max protobuf extension
172 If 'yang' is specified, then the number of elements specified in
173 the yang 'max-elements' statement is used. If there is no
174 'max-elements' statement, the behavior defaults to 'none'.
176 If a decimal integer is specified, that number is used as the
179 If this extension is not specified, the behavior defaults to
180 'yang'. Descendant list and leaf-list objects do not inherit
184 extension field-string-max {
187 "Set the protobuf field 'string_max' option for a leaf or
188 leaf-list of type string, binary, leafref, identityref, or
189 instance-identifier. Allowed values are a positive decimal
190 integer, 'yang', or 'none'. An optional encoding specifier may
191 also be specified, as octet or utf8, which specifies how
192 characters are counted. If specified, the encoding must come
193 first. Example limits:
202 If 'none' is specified, then the string_max protobuf extension
203 will not be used. 'none' cannot be combined with 'octet' or
206 If 'yang' is specified, the yang type must be string or binary.
207 If the yang type includes the length statement, then the
208 statements maximum length is used as the length. Otherwise,
209 behavior defaults to 'none'.
211 If a decimal integer is specified, that number is used as the
214 The encoding specifiers are used to determine the actual number
215 of bytes used in the protobuf extension. If the 'octet'
216 specifier is used, then the maximum length is used literally as
217 the byte length. If the 'utf8' specified is used, then the
218 maximum length is considered to be in terms of worst-case UTF-8
219 characters, in which case the protobuf byte length will actually
220 be 4 times the specified length.
222 For string and binary types, the default encoding is 'octet'.
223 For the remaining types, the default encoding is 'utf8',
224 reflecting those types fundemental description as XML entities
225 assumed to be encoded in UTF-8.
227 If this extension is not specified, then the default is 'yang'
228 for string and binary, and 'none' for the other types. This
229 extension cannot be specified on aggregate objects, and so it
230 cannot be inherited.";
233 extension field-tag {
236 "Set the protobuf field tag. Allowed values are a positive
237 decimal integer, 'auto', a base-relative addition expression, or
238 a field-relative addition expression.
240 If a decimal integer is specified, then the tag is set to the
241 specified number. You should avoid using this form in a
242 grouping, because you may not be able to guarantee uniqueness
243 across all the uses of the group. However, the syntax will be
246 A base-relative addition expression allows the tag of a field to
247 be defined in terms of the base tag of an enclosing grouping,
248 container, list, or uses statement. The expression has the form
249 '+NUMBER', where NUMBER is the value to add to the base to derive
250 the current field's tag.
252 A field-relative addition expression allows the tag of one field
253 to be defined in terms of another field. The expression has the
254 form 'NAME+NUMBER', where NAME is the name of the other field,
255 and NUMBER is the value to add to the other fields tag to derive
256 the current field's tag.
258 If this extension is not specified, the default behavior is
262 extension field-type {
265 "Override the default protobuf field type mapping for a leaf or
266 leaf-list type, and use the specified protobuf type instead.
268 Allowed values are any of the Protobuf scalar types, as
269 restricted by the yang leaf type:
271 +---------------------------+-------------------------------+
272 | (pseudo) yang leaf type | (pseudo) protobuf scalar type |
273 |---------------------------+-------------------------------+
274 | int8, int16, int32 | int32, sint32, sfixed32, auto |
275 +---------------------------+-------------------------------+
276 | int64 | int64, sint64, sfixed64, auto |
277 +---------------------------+-------------------------------+
278 | uint8, uint16, uint32 | uint32, fixed32, auto |
279 +---------------------------+-------------------------------+
280 | uint64 | uint64, fixed64, auto |
281 +---------------------------+-------------------------------+
282 | decimal | uint64, sint64, int64, |
283 | | fixed64, sfixed64, |
284 | | float, double, auto |
285 +---------------------------+-------------------------------+
286 | empty, boolean | bool, auto |
287 +---------------------------+-------------------------------+
288 | string, leafref, | string, auto |
290 | instance-identifier, | |
292 +---------------------------+-------------------------------+
293 | bits, binary | bytes, auto |
294 +---------------------------+-------------------------------+
296 If 'auto' is specified, the default conversion will be used. The
297 protobuf pseudo-type utf8 is equivalent to string, except that
298 length limits will be adjusted in protobuf extentions to allow
299 the string to be composed entirely of the maximum sized UTF-8
300 multibyte characters (byte length is 4 times larger than the
304 extension field-c-type {
307 "Override the default protoc-c C-language type mapping for a leaf
308 or leaf-list type, and use the specified C type instead.";
311 /* ATTN: Stop using this extension? */
312 extension package-name {
315 "Specifies the name of the package name in the generated .proto
316 file on a module statement The argument is the name of the
317 package-name. Allowed values are valid C identifiers When
318 package-name is not specified the generated package name defaults
319 to the Yang module name";
322 extension application-request-point {
324 "This extension is used temporarily until the config and data portions
325 are split into different namespaces and keyspecs. This allows
326 applications to provide data at a keyspec, and request config at a
330 extension enum-name {
333 "Use the specified name for the enum enumerator in the .proto
334 instead of the default mangled name of the yang identifer.
335 If there is a name conflict with other enum name either specified
336 explicitly or generated one, the yangpbc conversion will fail.
337 Allowed values are valid C identifiers.";
340 extension enum-type {
341 argument "enumtypename";
343 "Use the specified name for the enum type in the .proto instead
344 of the default mangled name of the yang identifier. If there is
345 a name conflict with another enum type, either auto-generated or
346 explicitly specified one, the yangpbc conversion will fail.
347 Allowed values are valid C identifiers.";
350 extension file-pbc-include {
351 argument "pathstring";
353 "A module level extension to specify the include files for pb-c.h
354 when any rift specific c-types are used. This extension can
355 occur multiple times as a child of module statement. The value
356 should be a valid path string.";
359 extension field-merge-behavior {
362 "An extension for controlling the merge done for listy types
363 during upacking of protobuf. It can take 3 different value:
365 1) default: The default is whatever protobuf-c does today
366 (for keyed lists, the default is equivalent to by-keys).
368 2) by-keys: allowed on keyed lists (and leaf-lists): merge
369 elements with matching key.
371 3) none: allowed on keyed lists (and leaf-lists): do not
372 attempt to merge elements. This must ONLY be used when it
373 is known or expected that the proto message would contain
374 large number of list items.";