Ki Types

Introduction

The Ki Type System (KTS) defines portable types used by Ki Declarative (KD), including KD Schema, and other Ki libraries. It is a modern type system with nullable and non-nullable types, generics and units of measure. KTS was modeled after type systems in languages such as Kotlin, Swift and C#.

KTS currently supports 21 literal types including data structures with type parameters:

Base Types

Type	Description	Examples	Notes
String	Unicode text	"hello", "ท้องฟ้า", "대양"	See String
Char	Unicode character	'A', 'Ж', '桜'
Int	32b signed integer	123, 424_235_412, 0xFF	Optional underscores for legibility
Long	64b signed integer	123L, 424_235_412L
Float	32b signed float	123.43F, 123.43f
Double	64b signed float	123.43, 123.43D, 123d, 5.421_523	Optional underscores for legibility
Dec	128b+ signed decimal	123.44BD, 123.44bd	See notes below*
Bool	boolean	true, false
URL	URL	https://www.nasa.gov, ldap://ds.example.com:389
Date	simple date	2005/12/05, 1592/4/8	See Date
LocalDateTime	local date & time	2021/12/05@05:21:23.53	See LocalDateTime
ZonedDateTime	date & time w/ zone	2021/12/05@05:21:23.53+03	See ZonedDateTime
Duration	length of time	12:74:42, 23days:05:21:23.53, 85ms	See Duration
Version	Version descriptor	4.2.5, 5.2-beta, 2.8.5-alpha-2	See Version
Blob	Binary Data	.blob(sdf789GSfsb2+3324sf2)	Base64 encoded; See Blob
Quantity<U>	An amount in Units	23cm, -15mL, 2.5m3, 2.5m³	see Quantity
Range<T>	Range for comparables	2..5, 2.0..<3.5, 2.0<.._	See Range
List<T>	Ordered list	[1 2 3], [4, 5, 6], ['a' 'b' 'c']	Commas optional; See List
Map<K, V>	Set of key=value pairs	[name="Rufus" color="rust"], ['a'=1, 'c'=3]	Commas optional; See Map
Call	Function call	rgb(120, 140, 20, alpha=.5)	Commas optional; See Call
nil	Absence of a value	nil, null

^*For platforms that do not support this level of precision, decimal should resolve to the most precise decimal representation possible and produce a warning.

Super Types

Type	Description	Base Types
Number	A scalar	Int, Long, Float, Double, Decimal
Any	Any value	All

Suffix a ? make a base or supertype nullable. For example: Int? means "Int or nil"

💡 Supertypes are used by libraries that interact with KTS such as KD Schema (KDS).

String

A String represents unicode text. KTS Strings can contain any unicode character. External representations should always use UTF-8 encoding.

Strings support the following escape characters:

Char	Description
\t	Tab
\b	Backspace
\n	New Line
\r	Carriage Return
\u	Unicode Escape
'	Single Quote
"	Double Quote
\	Backslash

DateTime Literals

KTS supports three DateTime types. LocalDateTime and ZonedDateTime provide nanosecond accuracy.

Type	Description
Date	A simple date with year/month/day
LocalDateTime	A local (relative) DateTime with year/month/day@hour:minute(:second(.fractional_second)?)?
ZonedDateTime	A DateTime with a time zone (see below)

Note: A time-of-day that isn't attached to a date can be represented by using a Duration treated as an offset from midnight.

Date

A Ki Date type is a calendar date with a year, month and day (no time component).

The canonical representation is year/month/day. Examples:

• 2005/12/05
• 2020/09/18
• 2020/9/18

LocalDateTime

LocalDateTime literals don't specify a time zone. They are to be interpreted as local (relative to the observer) time.

Canonical Form: yyyy/mm/dd @hh:mm(:ss(.fractional)?)?

Example	Description
2005/09/05 @05:08:03.532	Date and time with all components zero padded

ZonedDateTime

ZonedDateTime literals specify a date, time and zone. Zones can be specified with -Z, -UTC, [+/-]offset, or -KiTZ:

Canonical Form: yyyy/mm/dd @hh:mm(:ss(.fractional)?)?(-Z | [+/-]offset)

Example	Description
2005/12/05@05:21:23.532-Z	UTC (no offset)
2005/12/05@05:21:23.532+2	UTC+02 offset
2005/12/05@05:21:23.532-2	UTC-02 offset
2005/12/05@05:21:23.532+2:30	UTC+02:30 offset

Duration

KTS Duration literals represent a length of time, which may be negative. Duration literals are useful for expressing the duration of an event, intervals, or chronological distances from a reference point.

Canonical Form Examples

Example	Description
03:00:00	3 hours
00:12:00	12 minutes
00:00:42	42 seconds
00:12:32.423	12 minutes, 32 seconds, 423 milliseconds
00:01:32.000002584	12 minutes, 32 seconds, 2,584 nanoseconds
30days:15:23:04.023	30 days, 15 hours, 23 mins, 4 secs, 23 milliseconds

Version

The KTS Version type uses a simple schema based on Semantic Versioning 2. All numeric components must be zero or positive integers.

Format: `major('.'minor('.'micro)?)?('-'qualifier(('-')?qualiferNumber)?)?`

Version Components

Component	Role	Description
major	Major feature release, possible breaking changes	positive integer
minor	Minor feature release, no breaking changes	positive integer
micro	Bug fixes and performance enhancement	positive integer
qualifier	Text label, e.g. "alpha", "beta" or "RC"	Unicode string
qualifierNumber	A positive integer (requires a qualifier)	positive integer

Comparing Versions

For the purpose of comparison and inclusion in ranges, the sort order compares numeric components and qualifier, if present, ignoring case. Versions that have qualifiers are sorted below versions that are otherwise equal without a qualifier (e.g. 5.2-alpha is lower than 5.2). Qualifiers are sorted by alphabetical ordering (case insensitive), and finally the qualifier number, if present, is compared.

Canonical Form Examples

1. 5.2.7
2. 5.0.0-beta-2
3. 5.2.0-alpha
4. 5.2.7-rc

Quantity

A Quantity is an amount of a Unit. KD supports all SI base axes and several popular derived axes:

SI Base Axes

1. Time (via Duration)
2. Length
3. Mass
4. Temperature (Celsius & Kelvin)
5. SubstanceAmount
6. Current
7. Luminosity

SI Derived Axes

1. Area
2. Volume
3. Speed
4. Density

Other derived axes are likely to be added in future versions.

You specify them using standard SI symbols. There is an exception for Liter (L). Due to a conflict with the "L" suffix for long literals, liter is written with "LT" or "ℓ" (e.g. 5LT or 5ℓ).

By default Quantities use the high precision Dec type for their value. You can override this behavior by adding a :i, :L, :d or :f suffix after the unit type for Int, Long, Double or Float.

Canonical Form Examples

1. 23cm
2. 51.4m3 or 51.4m³
3. 97LT or 97ℓ
4. 1000kg or 1_000kg
5. 142.24km:d # This forces the value to be stored as a Double rather than a Dec

Range

Ranges can be created for all KTS base types (numbers, chars, Strings, etc.) They can be inclusive or exclusive on either side. They can also be open on either side. Here are some examples:

Example	Description
1..5	Range<Int> 1 - 5 (inclusive)
5.0<..<15.0	Range<Double> > 5, < 15 (exclusive)
2<..17	Range<Int> > 2, <= 17 (exclusive-left)
6..<12	Range<Int> >= 6, < 12, (exclusive-right)
6.._	Range<Int> >= 6 (open-right)
_..100	Range<Int> <= 100 or less (open-left)
8<.._	Range<Int> > 8, (exclusive-left, open-right)
'a'..'f'	Range<Char> >= 'a', <='f' (inclusive)
7.2.5-beta-2.._	Range<Version> >= 7.2.5-beta-2 (inclusive, open-right)

Blob

A KTS Blob is a byte array, normally represented as a byte array or encoded with Base64 encoding.

Canonical Form: .blob(base64_chars)

List

A KTS List is an ordered list of KTS Objects. Lists can be typed (e.g. List<Int>).

Canonical Form: [obj1, obj2, obj3]

Map

A KTS Map is an unordered dictionary of key-value pairs. Maps can by typed (e.g. Map<String, Int>)

Canonical Form: [key1=val1, key2=val2, key3=val3]

Call

A KTS Call is a data representation of a function call (invocation). Calls have positional and named parameters.

Canonical Form: rgb(200, 120, 100, alpha=.5)