schema.rst
1 ==================== 2 Serialization Schema 3 ==================== 4 5 This document details the existing mappings in NimYAML from Nim types to YAML 6 tags. Throughout this document, there are two *tag shorthands* being used: 7 8 ========= ========================= 9 Shorthand Expansion 10 ========= ========================= 11 ``!!`` ``tag:yaml.org,2002:`` 12 ``!n!`` ``tag:nimyaml.org,2016:`` 13 ========= ========================= 14 15 The first one is defined by the YAML specification and is used for types from 16 the YAML failsafe, JSON or core schema. The second one is defined by NimYAML and 17 is used for types from the Nim standard library. 18 19 The YAML tag system has no understanding of generics. This means that NimYAML 20 must map every generic type instance to a YAML tag that describes that exact 21 type instance. For example, a ``seq[string]`` is mapped to the tag 22 ``!n!system:seq(tag:yaml.org;2002:string)``. 23 24 As you can see, the expanded tag handle of the generic type parameter is added 25 to the tag of the generic type. To be compliant with the YAML spec, the 26 following modifications are made: 27 28 * Any exclamation marks are removed from the expanded tag. An exclamation mark 29 may only occur at the beginning of the tag as defined by the YAML spec. 30 * Any commas are replaces by semicolons, because they may not occur in a tag 31 apart from within the tag handle expansion. 32 33 If a type takes multiple generic parameters, the tag handles are separated by 34 semicolons within the parentheses. Note that this does not guarantee unique tag 35 handles for every type, but it is currently seen as good enough. 36 37 Note that user-defined generic types are currently not officially supported by 38 NimYAML. Only the generic collection types explicitly listed here use this 39 mechanism for crafting YAML tags. 40 41 Scalar Types 42 ============ 43 44 The following table defines all non-composed, atomar types that are mapped to 45 YAML types by NimYAML. 46 47 ========= =========================================================== 48 Nim type YAML tag 49 ========= =========================================================== 50 char ``!n!system:char`` 51 string ``!!string`` (or ``!n!nil:string`` if nil) 52 int ``!n!system:int32`` (independent on target architecture) 53 int8 ``!n!system:int8`` 54 int16 ``!n!system:int16`` 55 int32 ``!n!system:int32`` 56 int64 ``!n!system:int64`` 57 uint ``!n!system:uint32`` (independent from target architecture) 58 uint8 ``!n!system:uint8`` 59 uint16 ``!n!system:uint16`` 60 uint32 ``!n!system:uint32`` 61 uint64 ``!n!system:uint64`` 62 float ``!n!system:float64`` 63 float32 ``!n!system:float32`` 64 float64 ``!n!system:float64`` 65 bool ``!!bool`` 66 Time ``!!timestamp`` 67 ========= =========================================================== 68 69 Apart from these standard library types, NimYAML also supports all enum types 70 as scalar types. They will be serialized to their string representation. 71 72 Apart from the types listed here and enum tyes, no atomar types are supported. 73 74 Collection Types 75 ================ 76 77 Collection types in Nim are typically generic. As such, they take their 78 contained types as parameters inside parentheses as explained above. The 79 following types are supported: 80 81 ============ ============================================================ ================================ 82 Nim type YAML tag YAML structure 83 ============ ============================================================ ================================ 84 array ``!n!system:array(?;?)`` (first parameter like ``0..5``) sequence 85 seq ``!n!system:seq(?)`` (or ``!n!nil:seq`` if nil) sequence 86 set ``!n!system:set(?)`` sequence 87 Table ``!n!tables:Table(?;?)`` mapping 88 OrderedTable ``!n!tables:OrderedTable(?;?)`` sequence of single-pair mappings 89 ============ ============================================================ ================================ 90 91 Standard YAML Types 92 =================== 93 94 NimYAML does not support all types defined in the YAML specification, **not even 95 those of the failsafe schema**. The reason is that the failsafe schema is 96 designed for dynamic type systems where a sequence can contain arbitrarily typed 97 values. This is not fully translatable into a static type system. NimYAML does 98 support some mechanisms to make working with heterogeneous collection structures 99 easier, see `Serialization Overview <serialization.html>`_. 100 101 Note that because the specification only defines that an implementation *should* 102 implement the failsafe schema, NimYAML is still compliant; it has valid reasons 103 not to implement the schema. 104 105 This is a full list of all types defined in the YAML specification or the 106 `YAML type registry <http://www.yaml.org/type/>`_. It gives an overview of which 107 types are supported by NimYAML, which may be supported in the future and which 108 will never be supported. 109 110 =============== ============================================ 111 YAML type Status 112 =============== ============================================ 113 ``!!map`` Cannot be supported 114 ``!!omap`` Cannot be supported 115 ``!!pairs`` Cannot be supported 116 ``!!set`` Cannot be supported 117 ``!!seq`` Cannot be supported 118 ``!!binary`` Currently not supported 119 ``!!bool`` Maps to Nim's ``bool`` type 120 ``!!float`` Not supported (user can choose) 121 ``!!int`` Not supported (user can choose) 122 ``!!merge`` Not supported and unlikely to be implemented 123 ``!!null`` Used for reference types that are ``nil`` 124 ``!!str`` Maps to Nim's ``string`` type 125 ``!!timestamp`` Maps to Nim's ``Time`` type 126 ``!!value`` Not supported and unlikely to be implemented 127 ``!!yaml`` Not supported and unlikely to be implemented 128 =============== ============================================ 129 130 ``!!int`` and ``!!float`` are not supported out of the box to let the user 131 choose where to map them (for example, ``!!int`` may map to ``int32`` or 132 ``int64``, or the the generic ``int`` whose size is platform-dependent). If one 133 wants to use ``!!int``or ``!!float``, the process is to create a ``distinct`` 134 type derived from the desired base type and then set its tag using 135 ``setTagUri``. 136 137 ``!!merge`` and ``!!value`` are not supported because the semantics of these 138 types would make a multi-pass loading process necessary and if one takes the 139 tag system seriously, ``!!merge`` can only be used with YAML's collection types, 140 which, as explained above, cannot be supported.