Lines Matching +full:json +full:- +full:schema
1 Writing a schema {#flatbuffers_guide_writing_schema}
4 The syntax of the schema language (aka IDL, [Interface Definition Language][])
44 optionally a default value. If the default value is not specified in the schema,
53 - You can add new fields in the schema ONLY at the end of a table
58 schema, you can manually assign ids (much like Protocol Buffers),
61 - You cannot delete fields you don't use anymore from the schema,
69 - You may change field names and table names, if you're ok with your
72 See "Schema evolution examples" below for more on this
82 tables and are even faster to access (they are always stored in-line in their
87 Built-in scalar types are
89 - 8 bit: `byte` (`int8`), `ubyte` (`uint8`), `bool`
91 - 16 bit: `short` (`int16`), `ushort` (`uint16`)
93 - 32 bit: `int` (`int32`), `uint` (`uint32`), `float` (`float32`)
95 - 64 bit: `long` (`int64`), `ulong` (`uint64`), `double` (`float64`)
101 Built-in non-scalar types:
103 - Vector of any other type (denoted with `[type]`). Nesting vectors
106 - `string`, which may only hold UTF-8 or 7-bit ASCII. For other text encodings
109 - References to other tables or structs, enums or unions (see
113 of same-size data where a `reinterpret_cast` would give you a desirable result,
119 Arrays are a convenience short-hand for a fixed-length collection of elements.
120 Arrays can be used to replace the following schema:
128 with the following schema:
140 There are three, mutually exclusive, reactions to the non-presence of a table's
143 1. Default valued fields will return the default value (as defined in the schema).
149 When writing a schema, values are a sequence of digits. Values may be optionally
151 optionally prefixed by a `-`. Floats may also be in scientific notation;
152 optionally ending with an `e` or `E`, followed by a `+` or `-` and more digits.
155 Only scalar values can have defaults, non-scalar (string/vector/table) fields
161 generated by the old schema old version, if they happen to be the default, will
162 be read as a different value by code generated with the new schema. This is
164 scalar since non-presence would not be overloaded with a previous default value.
211 open-ended way, for example for use as files, see the file identification
236 When using the `flatc` compiler to generate code for schema definitions,
243 data. This is particularly important for parsing JSON data, which doesn't
248 Typically, a FlatBuffer binary buffer is not self-describing, i.e. it
249 needs you to know its schema to parse it correctly. But if you
256 but FlatBuffers has a built-in way to add an identifier to a
260 You can specify in a schema, similar to `root_type`, that you intend
266 will end up as bytes at offsets 4-7 (inclusive) in the buffer.
268 For any schema that has such an identifier, `flatc` will automatically
269 add the identifier to any binaries it generates (with `-b`),
278 Note that this is best for open-ended uses such as files. If you simply wanted
283 This declaration in the schema will change that to whatever you want:
289 You can declare RPC calls in a schema, that define a set of functions
299 used, there is preliminary support for GRPC through the `--grpc` code generator,
304 May be written as in most C-based languages. Additionally, a triple
317 available to query if you parse the schema at runtime.
324 - `id: n` (on a table field): manually set the field identifier to `n`.
329 field and not explicitly declared in the schema).
333 IDs allow the fields to be placed in any order in the schema.
334 When a new field is added to the schema it must use the next available ID.
335 - `deprecated` (on a field): do not generate accessors for this field
340 - `required` (on a non-scalar table field): this field must always be set.
343 flexibility of data structures. By specifying this attribute, you make non-
351 - `force_align: size` (on a struct): force the alignment of this struct
357 `--object-api`, since that may allocate objects at alignments less than
359 - `force_align: size` (on a vector): force the alignment of this vector to be
362 - `bit_flags` (on an unsigned enum): the values of this field indicate bits,
363 meaning that any unsigned value N specified in the schema will end up
366 - `nested_flatbuffer: "table_name"` (on a field): this indicates that the field
370 - `flexbuffer` (on a field): this indicates that the field
373 - `key` (on a field): this field is meant to be used as a key when sorting
374 a vector of the type of table it sits in. Can be used for in-place
376 - `hash` (on a field). This is an (un)signed 32/64 bit integer field, whose
377 value during JSON parsing is allowed to be a string, which will then be
380 - `original_order` (on a table): since elements in a table do not need
384 - 'native_*'. Several attributes have been added to support the [C++ object
389 ## JSON Parsing
391 The same parser that parses the schema declarations above is also able
392 to parse JSON objects that conform to this schema. So, unlike other JSON
397 Besides needing a schema, there are a few other changes to how it parses
398 JSON:
400 - It accepts field names with and without quotes, like many JSON parsers
403 - If a field has an enum type, the parser will recognize symbolic enum
411 - Similarly, for unions, these need to specified with two fields much like
415 - A field that has the value `null` (e.g. `field: null`) is intended to
418 - It has some built in conversion functions, so you can write for example
423 When parsing JSON, it recognizes the following escape codes in strings:
425 - `\n` - linefeed.
426 - `\t` - tab.
427 - `\r` - carriage return.
428 - `\b` - backspace.
429 - `\f` - form feed.
430 - `\"` - double quote.
431 - `\\` - backslash.
432 - `\/` - forward slash.
433 - `\uXXXX` - 16-bit unicode code point, converted to the equivalent UTF-8
435 - `\xXX` - 8-bit binary hexadecimal number XX. This is the only one that is
436 not in the JSON spec (see http://json.org/), but is needed to be able to
438 information (e.g. the byte 0xFF can't be represented in standard JSON).
440 It also generates these escape codes back again when generating JSON from a
443 When parsing numbers, the parser is more flexible than JSON.
448 - An integer literal can have any number of leading zero `0` digits.
451 The numbers `[081, -00094]` are equal to `[81, -94]` decimal integers.
452 - The parser accepts unsigned and signed hexadecimal integer numbers.
453 For example: `[0x123, +0x45, -0x67]` are equal to `[291, 69, -103]` decimals.
454 - The format of float-point numbers is fully compatible with C/C++ format.
456 floating-point literals as well:
457 `[-1.0, 2., .3e0, 3.e4, 0x21.34p-5, -inf, nan]`.
459 The following conventions for floating-point numbers are used:
460 - The exponent suffix of hexadecimal floating-point number is mandatory.
461 - Parsed `NaN` converted to unsigned IEEE-754 `quiet-NaN` value.
463 Extended floating-point support was tested with:
464 - x64 Windows: `MSVC2015` and higher.
465 - x64 Linux: `LLVM 6.0`, `GCC 4.9` and higher.
469 - For compatibility with a JSON lint tool all numeric literals of scalar
471 `"1", "2.0", "0x48A", "0x0C.0Ep-1", "-inf", "true"`.
478 require an efficient schema. There are usually multiple choices on
482 (as in e.g. JSON), because of its flexibility and extensibility. While
493 truly open-ended. If you can, always use an enum instead.
500 Again, this is efficient because non-present fields are cheap.
511 Identifiers in a schema are meant to translate to many different programming
518 identifiers that adhere to the language style, based on the schema identifiers.
520 - Table, struct, enum and rpc names (types): UpperCamelCase.
521 - Table and struct field names: snake_case. This is translated to lowerCamelCase
523 - Enum values: UpperCamelCase.
524 - namespaces: UpperCamelCase.
528 - Opening brace: on the same line as the start of the declaration.
529 - Spacing: Indent by 2 spaces. None around `:` for types, on both sides for `=`.
531 For an example, see the schema at the top of this file.
544 A adds a field, generates new binary data with this new schema, then tries to
546 and just auto-merges the schema, the binary files are now invalid compared to
547 the new schema.
550 your schema changes have been committed, ensuring consistency with the rest of
555 ### Schema evolution examples (tables)
557 Some examples to clarify what happens as you change a schema:
559 If we have the following original schema:
567 This is ok. Code compiled with the old schema reading data generated with the
569 new schema reading old data will get the default value for `c` (which is 0
574 This is also ok. Code compiled with the old schema reading newer data will now
576 with the new schema now cannot read nor write `a` anymore (any existing code
590 with the original schema, and the fields can be ordered in any way, as long as
613 Occasionally ok. You've renamed fields, which will break all code (and JSON
614 files!) that use this schema, but as long as the change is obvious, this is not
618 #### Schema evolution examples (unions)
620 Suppose we have the following schema:
645 such as json files, but the binary buffers will be the same.
656 Most serialization formats (e.g. JSON or Protocol Buffers) make it very
662 cannot disambiguate the meaning of non-presence as "written default value" or
667 scalars." You can set `null` as the default value in the schema. `null` is a