Values

TypeSpec can define values in addition to types. Values are useful in an API description to define default values for types or provide example values. They are also useful when passing data to decorators, and for template parameters that are ultimately passed to decorators or used as default values.

Values cannot be used as types, and types cannot be used as values, they are completely separate. However, string, number, boolean, and null literals can be either a type or a value depending on context (see also scalar literals). Additionally, union and enum member references may produce a type or a value depending on context (see also enum member & union variant references).

Value kinds

There are four kinds of values: objects, arrays, scalars. and null. These values can be created with object values, array values, scalar values and initializers, and the null literal respectively. Additionally, values can result from referencing enum members and union variants.

Object values

Object values use the syntax #{} and can define any number of properties. For example:

const point = #{ x: 0, y: 0 };

The object value's properties must refer to other values. It is an error to reference a type.

const example = #{
  prop1: #{ nested: true }; // ok
  prop2: { nested: true }; // error: values can't reference a type
  prop3: string; // error: values can't reference a type
}

Array values

Array values use the syntax #[] and can define any number of items. For example:

const points = #[#{ x: 0, y: 0 }, #{ x: 1, y: 1 }];

As with object values, array values cannot contain types.

If an array type defines a minimum and maximum size using the @minValue and @maxValue decorators, the compiler will validate that the array value has the appropriate number of items. For example:

/** Can have at most 2 tags */
@maxItems(2)
model Tags is Array<string>;

const exampleTags1: Tags = #["TypeSpec", "JSON"]; // ok
const exampleTags2: Tags = #["TypeSpec", "JSON", "OpenAPI"]; // error

Scalar values

There are two ways to create scalar values: with a literal syntax like "string value", and with a scalar initializer like utcDateTime.fromISO("2020-12-01T12:00:00Z").

Scalar literals

The literal syntax for strings, numerics, booleans and null can evaluate to either a type or a value depending on the surrounding context of the literal. When the literal is in type context (a model property type, operation return type, alias definition, etc.) the literal becomes a literal type. When the literal is in value context (a default value, property of an object value, const definition, etc.), the literal becomes a value. When the literal is in an ambiguous context (e.g. an argument to a template or decorator that can accept either a type or a value) the literal becomes a value. The typeof operator can be used to convert the literal to a type in such ambiguous contexts.

extern dec setNumberValue(target: unknown, color: valueof numeric);
extern dec setNumberType(target: unknown, color: numeric);
extern dec setNumberTypeOrValue(target: unknown, color: numeric | (valueof numeric));

@setNumberValue(123) // Passes the scalar value `numeric(123)`.
@setNumberType(123) // Passes the numeric literal type 123.
@setNumberTypeOrValue(123) // passes the scalar value `numeric(123)`.
model A {}

Scalar initializers

Scalar initializers create scalar values by calling an initializer with one or more values. Scalar initializers for types extended from numeric, string, and boolean are called by adding parenthesis after the scalar reference:

const n = int8(100);
const s = string("hello");

Any scalar can additionally be declared with named initializers that take one or more value parameters. For example, utcDateTime provides a fromISO initializer that takes an ISO string. Named scalars can be declared like so:

scalar ipv4 extends string {
  init fromInt(value: uint32);
}

const ip = ipv4.fromInt(2341230);

Null values

Null values are created with the null literal.

const value: string | null = null;

The null value, like the null type, doesn't have any special behavior in the TypeSpec language. It is just the value null like that in JSON.

Const declarations

Const declarations allow storing values in a variable for later reference. Const declarations have an optional type annotation. When the type annotation is absent, the type is inferred from the value by constructing an exact type from the initializer.

const stringValue: string = "hello";
//      ^-- type: string

const oneValue = 1;
//      ^-- type: 1

const objectValue = #{ x: 0, y: 0 };
//      ^-- type: { x: 0, y: 0 }

The typeof operator

The typeof operator returns the declared or inferred type of a value reference. Note that the actual value being stored by the referenced variable may be more specific than the declared type of the value. For example, if a const is declared with a union type, the value will only ever store one specific variant at a time, but typeof will give you the declared union type.

const stringValue: string = "hello";
// typeof stringValue returns `string`.

const oneValue = 1;
// typeof stringValue returns `1`

const stringOrOneValue: string | 1 = 1;
// typeof stringOrOneValue returns `string | 1`

Validation

TypeSpec will validate values against built-in validation decorators like @minLength and @maxValue.

@maxLength(3)
scalar shortString extends string;

const s1: shortString = "abc"; // ok
const s2: shortString = "abcd"; // error:

model Entity {
  a: shortString;
}

const e1: Entity = #{ a: "abcd" }; // error

Enum member & union variant references

References to enum members and union variants can be either types or values and follow the same rules as scalar literals. When an enum member reference is in type context, the reference becomes an enum member type. When in value context or ambiguous context the reference becomes the enum member's value.

extern dec setColorValue(target: unknown, color: valueof string);
extern dec setColorMember(target: unknown, color: Reflection.EnumMember);

enum Color {
  red,
  green,
  blue,
}

@setColorValue(Color.red) // same as passing the literal "red"
@setColorMember(Color.red) // passes the enum member Color.red
model A {}

When a union variant reference is in type context, the reference becomes the type of the union variant. When in value context or ambiguous context the reference becomes the value of the union variant. It is an error to refer to a union variant whose type is not a literal type.

extern dec setColorValue(target: unknown, color: valueof string);
extern dec setColorType(target: unknown, color: string);

union Color {
  red: "red",
  green: "green",
  blue: "blue",
  other: string,
}

@setColorValue(Color.red) // passes the scalar value `string("red")`
@setColorValue(Color.other) // error, trying to pass a type as a value.
@setColorType(Color.red) // passes the string literal type `"red"`
model A {}