[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Proposed changes for chapter 4.4.1: Primitive Types
This section presents handling data in TOSCA via properties, attributes and parameters.
The type of the values they contain can be divided into built-in primitive types, special types that are extensions of the primitive types, and collection types, as well as user-defined refinements of these and complex data types that can themselves be defined in TOSCA profiles and the TOSCA service template.
Values can also be evaluated from expressions based on TOSCA functions. [See XXX]
The following table summarizes the built-in types. All of these type names are reserved and cannot be used for custom data types. Note, however, that it is possible to derive a custom data type from a primitive type in order to add constraints.
Primitive Types: (section 4.4.1)
string
integer
float
boolean
bytes
nil
Special Types: (section 4.4.2)
range
timestamp
scalar-unit.size
scalar-unit.time
scalar-unit.frequency
scalar-unit.bitrate
Collection Types: (section 4.4.3)
list
map
[Tal's comment: the Data Type section would thus be pushed to 4.4.4]
The TOSCA primitive types have been specified to allow for the broadest possible support for implementations.
Guiding principles:
Because TOSCA service templates are written in YAML they must support all the literal primitives in YAML. However, it is important to also allow for consistency of representation of external data, e.g. service template inputs and outputs, property and attribute values stored in a database, etc.
Adherence to 64-bit precision to ensure portability of numeric data.
TOSCA parsers shall not automatically convert between primitive types. Thus, care should be taken to use the correct YAML notation for that type. Details will be provided below.
An array of Unicode runes. (For storing an arbitrary array of bytes see the âbytesâ type, below.)
Because we adhere to 64-bit precision, the minimum length of strings is 0 and the maximum length of strings is 4,294,967,295.
TOSCA does not specify a character encoding. For example, a string could be encoded as UTF-8 or UTF-16. The exact encoding used depends on the implementation.
Be aware that YAML parsers will attempt to parse unquoted character sequences as other types (booleans, integers, floats, etc.) before falling back to the !!string type. For example, the unquoted sequence â0.1â would be interpreted as a YAML !!float. Likewise for the unquoted sequence ânanâ would become the !!float value of not-a-number. However, in TOSCA a string value must be specified in YAML as a !!string.
A TOSCA parser shall not attempt to convert other primitive types to strings if a string type is required. This requirement is necessary for ensuring portability, because there is no single, standard representation for the other types, e.g. scientific notations for decimals, the words âtrueâ va. âTrueâ for booleans, etc. In YAML users should thus add quotation marks around literal strings that YAML would otherwise interpret as other types.
This following example would be invalid if there were no quotation marks around â0.1â:
node_types:
ÂÂNode:
 properties:
name:
type: string
topology_template:
ÂÂnode_templates:
 node:
type: Node
properties:
name: "0.1"
Notes:
There are various ways to specify literal !!string data in YAML for handling indentation, newlines, as well as convenient support for line folding for multiline strings. All may be used in TOSCA. A TOSCA parser shall not modify the YAML string in any way, e.g. no trimming of whitespace or newlines. [YAML 1.2 chapter 6]
The TOSCA functions âconcatâ, âjoinâ, and âtokenâ and the TOSCA constraints âlengthâ, âmin_lengthâ, âmax_lengthâ, and âpatternâ are all Unicode-aware. Specifically the length of a string is a count of its runes, not the length of the byte array, which may differ according to the encoding. [See XXX]
The TOSCA constraints that check for equality, âequalâ and âvalid_valuesâ, should work regardless of the Unicode encoding. For example, comparing two strings that are â!â, one of which is in UTF-8 and is encoded as â0x21â, the other which is in UTF-16 and is encoded as â0x0021â, would result in equality. For simplicity, implementations may standardize on a single encoding, e.g. UTF-8, and convert all other encodings to it. [See XXX]
Relatedly, although in YAML 1.2 a !!string is already defined as a Unicode sequence [YAML 1.2 section 10.1.1.3], this sequence can be variously encoded according to the character set and encoding of the YAML stream [YAML 1.2 chapter 5]. The consequence is that a TOSCA string specified in literal YAML may inherit the encoding of the YAML document. Again, implementations may prefer to convert all strings to a single encoding.
TOSCA strings cannot be the null value but can be empty strings (a string with length zero). [See ânilâ, below]
YAML is a streaming format, but TOSCA strings are explicitly not streams and thus do have a size limit. Thus, TOSCA implementations should check against the size limit.
[Talâs comment: for functions and constraints we should specify their exact behavior for various primitive types. Some wonât work on all types, e.g. âlengthâ should not work on integers.]
A 64-bit signed integer.
For simplicity, TOSCA does not have integers of other bit widths, nor does it have an unsigned integer type. However, it is possible to enforce most of these variations using data type constraints [see XXX].
For example, this would be a custom data type for unsigned 16-bit integers:
data_types:
ÂÂUInt16:
 derived_from: integer
 constraints:
 - in_range: [ 0, 0xFFFF ]
Notes:
YAML allows for the standard decimal notation as well as hexadecimal and octal notations [YAML 1.2 example 2.19]. In the above example we indeed used the hexadecimal notation.
The JSON schema for YAML 1.2 [YAML 1.2 chapter 10.2] allows for compatibility with JSON, such that YAML would be a superset of JSON. However, note that the JSON format does not distinguish between integers and floats, and thus many JSON implementations use floats instead of integers.
TOSCA does not specify the endianness of integers and indeed makes no requirements for data representation.
A 64-bit (double-precision) floating-point number [IEEE 754], including the standard values for negative infinity, positive infinity, and not-a-number.
Be aware that YAML parsers will parse numbers with a decimal point as !!float even if they could be represented as !!int, and likewise numbers without a decimal point would always be parsed as !!int.
A TOSCA parser shall not attempt to convert a YAML !!int to a float. This requirement is necessary for avoiding rounding errors and ensuring portability. Users should thus add a â.0â suffix to literal integers that must be floats. Note that this even includes zero, i.e. users must specify â0â for a zero integer and â0.0â for a zero float.
This following example would be invalid if there were no â.0â suffix added to â10â:
node_types:
ÂÂNode:
ÂÂ properties:
ÂÂÂÂÂÂvelocity:
ÂÂÂÂ Â type: float
topology_template:
ÂÂnode_templates:
 node:
ÂÂÂÂÂÂtype: Node
ÂÂÂÂÂ properties:
ÂÂ ÂÂÂ velocity: 10.0
Notes:
In addition to decimal, YAML also allows for specifying floats using scientific notation as well as special unquoted words for negative infinity, positive infinity, and not-a-number [YAML 1.2 example 2.20].
TOSCA does not specify how to convert to other precisions nor to other formats, e.g. Bfloat16 and TensorFloat-32.
TOSCA does not specify the endianness of floats and indeed makes no requirements for data representation.
A single bit.
Note that in YAML literal booleans can be only either the unquoted all-lowercase words âtrueâ or âfalseâ.
A TOSCA parser shall not attempt to convert these values, nor variations such as âyesâ or âTrueâ, as quoted strings to booleans, nor shall it attempt to convert integer values (such as 1 and 0) to booleans. This requirement is necessary for ensuring portability as well as clarity.
An array of arbitrary bytes. Because we adhere to 64-bit precision, the minimum length of bytes is 0 and the maximum length of bytes is 4,294,967,295.
To specify literal bytes in YAML you must use a Base64-encoded !!string [RFC 2045 section 6.8]. There exist many free tools to help you convert arbitrary data to Base64.
Example:
node_types:
ÂÂNode:
 properties:
ÂÂ Â preamble:
ÂÂÂÂ Â type: bytes
topology_template:
ÂÂnode_templates:
ÂÂ node:
ÂÂÂ type: Node
ÂÂÂÂÂÂproperties:
ÂÂÂÂÂÂ preamble: "\
R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5\
OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+\
+f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC\
AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs="
Notes:
There is no standard way to represent literal bytes in YAML 1.2. Though some YAML implementations may support the !!binary type working draft, to ensure portability TOSCA implementations shall not accept this YAML type.
The TOSCA constraints âlengthâ, âmin_lengthâ, and âmax_lengthâ work differently for the bytes type vs. the string type. For the latter the length is the count of Unicode runes, not the count of bytes.
TOSCA bytes values cannot be the null value but can be empty arrays (a bytes value with length zero). [See ânilâ, below]
The nil type always has the same singleton value. No other type can have this value.
This value is provided literally in YAML via the unquoted all-lowercase word ânullâ. Example:
node_types:
ÂÂNode:
 properties:
ÂÂÂÂÂÂnothing:
ÂÂ ÂÂÂ type: nil
ÂÂÂÂ Â required: true
topology_template:
ÂÂnode_templates:
ÂÂ node:
ÂÂÂÂ type: Node
ÂÂÂÂ properties:
ÂÂÂÂÂÂ nothing: null
Note that a nil-typed value is distinct from an unassigned value. For consistency TOSCA requires you to assign nil values even though their value is obvious. Thus, the above example would be invalid if we did not specify the null value for the property at the node template.
Following is a valid example of not assigning a value:
node_types:
ÂÂNode:
 properties:
ÂÂÂÂÂÂnothing:
ÂÂ ÂÂÂ type: nil
ÂÂÂÂ Â required: false
topology_template:
ÂÂnode_templates:
 node:
ÂÂ Â type: Node
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]