skyquake/plugins/composer/src/schemas/yang/rw-pb-ext.yang.src

   1
   2 /*
   3  *
   4  *   Copyright 2016 RIFT.IO Inc
   5  *
   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
   9  *
  10  *       http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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.
  17  *
  18  */
  19
  20
  21
  22 /**
  23  * @file rw-pb-ext.yang
  24  * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg
  25  * @date 2013/03/21
  26  * @brief RiftWare yang to protobuf conversion extensions
  27  */
  28
  29 module rw-pb-ext
  30 {
  31   namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext";
  32   prefix "rwpb";
  33
  34   revision 2014-03-28 {
  35     description
  36       "Initial revision.";
  37     reference
  38       "RIFT yang extensions for converting yang files to Google
  39       Protocol Buffers (protobuf) using rift protoc-c extensions.";
  40   }
  41
  42   extension msg-new {
  43     argument "typename";
  44     description
  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.
  49
  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.";
  54   }
  55
  56   extension msg-name {
  57     argument "typename";
  58     description
  59       "Change the name of an embedded protobuf message type for this
  60       container or list.  Allowed values are valid C identifiers.
  61
  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
  66       overridden.
  67
  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.";
  71   }
  72
  73   extension msg-flat {
  74     argument "selection";
  75     description
  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.
  81
  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.";
  85   }
  86
  87   extension msg-tag-base {
  88     argument "value";
  89     description
  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
  93       decimal integers.";
  94     // ATTN:  would really like to specify field-relative in uses!
  95   }
  96
  97 /*
  98   extension msg-tag-reserve {
  99     argument "value";
 100     description
 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.";
 105   }
 106 */
 107
 108   extension msg-proto-max-size {
 109     argument "value";
 110     description
 111       "Specify the maximum size of this message in the C structure or
 112       so in bytes.  Allowed values are positive decimal integers.";
 113   }
 114
 115   extension msg-typedef {
 116     argument "typename";
 117     description
 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.
 121
 122       typename will be appended to the mangeled protobuf package name
 123       and an underscore, to ensure name uniqueness across the global
 124       schema.
 125
 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.";
 130   }
 131
 132   extension field-name {
 133     argument "fieldname";
 134     description
 135       "Change the name of the element to fieldname, when converting the
 136       object to protobuf.  Allowed values are valid C identifiers.
 137
 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.";
 143   }
 144
 145   extension field-inline {
 146     argument "selection";
 147     description
 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
 152       setting.
 153
 154       When applied to a container or list statement, this extension is
 155       inherited by all enclosed objects, unless overridden.";
 156   }
 157
 158   extension field-inline-max {
 159     argument "limit";
 160     description
 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:
 164
 165         '64'
 166         'yang'
 167         'none'
 168
 169       If 'none' is specified, then the inline_max protobuf extension
 170       will not be used.
 171
 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'.
 175
 176       If a decimal integer is specified, that number is used as the
 177       maximum length.
 178
 179       If this extension is not specified, the behavior defaults to
 180       'yang'.  Descendant list and leaf-list objects do not inherit
 181       this extension.";
 182   }
 183
 184   extension field-string-max {
 185     argument "limit";
 186     description
 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:
 194
 195         'octet 64'
 196         'utf8 20'
 197         'utf8 yang'
 198         'utf8'
 199         '128'
 200         'none'
 201
 202       If 'none' is specified, then the string_max protobuf extension
 203       will not be used.  'none' cannot be combined with 'octet' or
 204       'utf8'.
 205
 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'.
 210
 211       If a decimal integer is specified, that number is used as the
 212       length.
 213
 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.
 221
 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.
 226
 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.";
 231   }
 232
 233   extension field-tag {
 234     argument "value";
 235     description
 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.
 239
 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
 244       allowed.
 245
 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.
 251
 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.
 257
 258       If this extension is not specified, the default behavior is
 259       'auto'.";
 260   }
 261
 262   extension field-type {
 263     argument "type";
 264     description
 265       "Override the default protobuf field type mapping for a leaf or
 266       leaf-list type, and use the specified protobuf type instead.
 267
 268       Allowed values are any of the Protobuf scalar types, as
 269       restricted by the yang leaf type:
 270
 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                  |
 289       | identityref,              |                               |
 290       | instance-identifier,      |                               |
 291       | anyxml                    |                               |
 292       +---------------------------+-------------------------------+
 293       | bits, binary              | bytes, auto                   |
 294       +---------------------------+-------------------------------+
 295
 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
 301       character length).";
 302   }
 303
 304   extension field-c-type {
 305     argument "type";
 306     description
 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.";
 309   }
 310
 311   /* ATTN: Stop using this extension? */
 312   extension package-name {
 313     argument "pkgname";
 314     description
 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";
 320   }
 321
 322   extension application-request-point {
 323     description
 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
 327        different level";
 328   }
 329
 330   extension enum-name {
 331     argument "enumname";
 332     description
 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.";
 338   }
 339
 340   extension enum-type {
 341     argument "enumtypename";
 342     description
 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.";
 348   }
 349
 350   extension file-pbc-include {
 351     argument "pathstring";
 352     description
 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.";
 357   }
 358
 359   extension field-merge-behavior {
 360     argument "value";
 361     description
 362       "An extension for controlling the merge done for listy types
 363        during upacking of protobuf. It can take 3 different value:
 364
 365        1) default: The default is whatever protobuf-c does today
 366           (for keyed lists, the default is equivalent to by-keys).
 367
 368        2) by-keys: allowed on keyed lists (and leaf-lists): merge
 369           elements with matching key.
 370
 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.";
 375   }
 376
 377 } // rw-pb-ext