Types

Here, you’ll find a comprehensive list of all types supported by the Typesync specification. Typesync’s powerful type system is designed to support a wide array of complex and useful types.

`any`

Represents any type.

Example:
  model: alias
  type: any

export type Example = any;

typealias Example = Any

import typing

Example = typing.Any

function isValidExample(data) {
  return true;
}

`unknown`

Represents an unknown type.

Example:
  model: alias
  type: unknown

export type Example = unknown;

typealias Example = Any

import typing

Example = typing.Any

function isValidExample(data) {
  return true;
}

`nil`

Represents the explicit absence of a value.

Example:
  model: alias
  type: nil

export type Example = null;

Example = None

function isValidExample(data) {
  return true;
}

`string`

Represents a string value.

Example:
  model: alias
  type: string

export type Example = string;

typealias Example = String

Example = str

function isValidExample(data) {
  return (data is string);
}

`boolean`

Represents a boolean value.

Example:
  model: alias
  type: boolean

export type Example = boolean;

typealias Example = Bool

Example = bool

function isValidExample(data) {
  return (data is bool);
}

`int`

Represents a signed integer.

Example:
  model: alias
  type: int

export type Example = number;

typealias Example = Int

Example = int

function isValidExample(data) {
  return (data is int);
}

`double`

Represents a double-precision floating point number.

Example:
  model: alias
  type: double

export type Example = number;

typealias Example = Double

Example = float

function isValidExample(data) {
  return (data is float);
}

`timestamp`

Represents a datetime value.

Example:
  model: alias
  type: timestamp

export type Example = firestore.Timestamp;

typealias Example = Date

import datetime

Example = datetime.datetime

function isValidExample(data) {
  return (data is timestamp);
}

`bytes`

Represents a Firestore bytes value.

Example:
  model: alias
  type: bytes

// Firebase Web targets emit firestore.Bytes; React Native Firebase emits firestore.Blob.
export type Example = Buffer;

typealias Example = Data

Example = bytes

function isValidExample(data) {
  return (data is bytes);
}

`document-reference`

Represents a Firestore document reference — a pointer to another Firestore document. Use this in place of storing a document ID as a string when you want the field to round-trip as a native reference under each Firestore SDK.

Firestore only supports storing document references in document fields, not collection references — the stored value’s path must end on a document id. The type name mirrors the SDK class DocumentReference to make this constraint obvious at the schema-definition layer.

Without an explicit model, the document-reference type intentionally does not encode the target document’s shape. If you want the generated TypeScript and Zod types to be narrowed to a specific target model, use the parameterized form below.

Example:
  model: alias
  type: document-reference

export type Example = firestore.DocumentReference<firestore.DocumentData>;

typealias Example = DocumentReference

Example = firestore.DocumentReference

function isValidExample(data) {
  return (data is path);
}

Parameterized form

document-reference also accepts an object form with an optional model field that names the target document (or alias) model. Typesync validates that the referenced model exists in the same schema and threads the target through to the generated code. The narrowing only takes effect on platforms whose Firestore SDK class is generic:

TypeScript — firestore.DocumentReference<TargetModel> is emitted instead of firestore.DocumentReference<firestore.DocumentData>.
Zod — the inferred type from z.infer<typeof Schema> carries the same narrowed shape. The runtime instanceof check is identical for both forms — narrowing is purely at the type level.
Python, Swift, Security Rules — these SDK classes are not generic, so the emitted type is identical to the bare form. The schema-level validation that model resolves still runs.

Zod self-references (e.g. NoteLink.next: DocumentReference<NoteLink>) are emitted without the generic in Zod to avoid TS2456 Type alias circularly references itself on the z.infer-derived type. Pure generate-ts output is unaffected and emits the narrowed self-reference. Cross-model references narrow on both targets.

Author:
  model: document
  path: authors/{authorId}
  type:
    type: object
    fields:
      name: { type: string }

Book:
  model: document
  path: books/{bookId}
  type:
    type: object
    fields:
      title: { type: string }
      author:
        type:
          type: document-reference
          model: Author

export interface Author {
  name: string;
}
export interface Book {
  title: string;
  author: firestore.DocumentReference<Author>;
}

class Author(TypesyncModel):
    name: str
class Book(TypesyncModel):
    title: str
    author: firestore.DocumentReference  # not narrowed; Python SDK class is not generic

struct Author: Codable {
    var name: String
}
struct Book: Codable {
    var title: String
    var author: DocumentReference  // not narrowed; iOS SDK class is not generic
}

`literal`

Represents a literal type.

Literal types are not supported in Swift. Typesync currently compiles literal types to the type of the literal value in Swift.

MeaningOfLife:
  model: alias
  type:
    type: literal
    value: 42

export type MeaningOfLife = 42;

typealias MeaningOfLife = Int

import typing

MeaningOfLife = typing.Literal[42]

function isValidMeaningOfLife(data) {
  return data == 42;
}

`enum`

Represents an enum value.

UserRole:
  model: alias
  docs: Represents a user's role within a project.
  type:
    type: enum
    members:
      - label: Owner
        value: owner
      - label: Admin
        value: admin
      - label: Member
        value: member

export type UserRole = 'owner' | 'admin' | 'member';

enum UserRole: String, Codable {
  case Owner = "owner"
  case Admin = "admin"
  case Member = "member"
}

import enum

class UserRole(enum.Enum):
    Owner = "owner"
    Admin = "admin"
    Member = "member"

function isValidUserRole(data) {
  return data == 'owner' || data == 'admin' || data == 'member';
}

`tuple`

Represents a tuple value.

Example:
  model: alias
  type:
    type: tuple
    elements:
      - string
      - boolean
      - int

export type Example = [string, boolean, number];

typealias Example = (String, Bool, Int)

Example = tuple[str, bool, int]

function isValidExample(data) {
  return ((data is list) && (data[0] is string) && (data[1] is bool) && (data[2] is int));
}

`list`

Represents a list of items.

Example:
  model: alias
  type:
    type: list
    elementType: string

export type Example = string[];

typealias Example = [String]

Example = typing.List[str]

function isValidExample(data) {
  return (data is list);
}

`map`

Represents a mapping from arbitrary strings to values of any type.

Example:
  model: alias
  type:
    type: map
    valueType: int

export type Example = Record<string, number>;

typealias Example = [String: Int]

import typing

Example = typing.Dict[str, int]

function isValidExample(data) {
  return (data is map);
}

`object`

Represents an object with known fields.

Example:
  model: alias
  type:
    type: object
    fields:
      name:
        type: string
      completed:
        type: boolean
      github_url:
        type: string
        optional: true

export type Example = {
  name: string;
  completed: boolean;
  github_url?: string;
};

struct Example: Codable {
  var name: String
  var completed: Bool
  var githubUrl: String?

  private enum CodingKeys: String, CodingKey {
    case name
    case completed
    case githubUrl = "github_url"
  }
}

# ...
class Example(TypesyncModel):
    name: str
    completed: bool
    github_url: typing.Union[TypesyncUndefined, str] = UNDEFINED
# ...

function isValidExample(data) {
  return (
    (data is map) &&
    (data.keys().hasOnly(['name', 'completed', 'github_url'])) &&
    (data.name is string) &&
    (data.completed is bool) &&
    ((data.github_url is string) || !('github_url' in data))
  );
}

Swift-specific options

Use swift.name on an object field to override only the generated Swift property name. The Firestore field name stays the same.

Example:
  model: alias
  type:
    type: object
    fields:
      class:
        type: string
        swift:
          name: userClass

struct Example: Codable {
  var userClass: String

  private enum CodingKeys: String, CodingKey {
    case userClass = "class"
  }
}

`union`

Represents a union of multiple types. Typesync supports two types of unions: simple union and discriminated union. Both are defined in the same way using variants, except a discriminated union definition has a discriminant key and requires every variant to be of object (or alias resolving to object) type. Simple Union Example

Path:
  model: alias
  type:
    type: union
    variants:
      - string
      - type: list
        elementType: string

export type Path = string | string[];

enum Example: Codable {
  case variant1(String)
  case variant2([String])

  private enum CodingKeys: String, CodingKey {
    case variant1
    case variant2
  }

  init(from decoder: Decoder) throws {
    let container = try decoder.singleValueContainer()
    if let variant1 = try? container.decode(String.self) {
      self = .variant1(variant1)
    } else if let variant2 = try? container.decode([String].self) {
      self = .variant2(variant2)
    } else {
      throw DecodingError.dataCorrupted(DecodingError.Context(codingPath: decoder.codingPath, debugDescription: "Failed to decode ExampleSimpleUnion value."))
    }
  }

  func encode(to encoder: Encoder) throws {
    var container = encoder.singleValueContainer()
    switch self {
    case .variant1(let val):
      try container.encode(val)
    case .variant2(let val):
      try container.encode(val)
    }
  }
}

Path = typing.Union[str, typing.List[str]]

function isValidPath(data) {
  return ((data is string) || (data is list));
}

Discriminated Union Example

Cat:
  model: alias
  type:
    type: object
    fields:
      type:
        type:
          type: literal
          value: cat
      name:
        type: string
      lives_left:
        type: int

Dog:
  model: alias
  type:
    type: object
    fields:
      type:
        type:
          type: literal
          value: dog
      name:
        type: string
      breed:
        type: string

Pet:
  model: alias
  type:
    type: union
    discriminant: type
    variants:
      - Cat
      - Dog

export type Cat = {
  type: 'cat';
  name: string;
  lives_left: number;
};

export type Dog = {
  type: 'dog';
  name: string;
  breed: string;
};

export type Pet = Cat | Dog;

struct Cat: Codable {
  private(set) var type: String = "cat"
  var name: String
  var livesLeft: Int

  private enum CodingKeys: String, CodingKey {
    case type
    case name
    case livesLeft = "lives_left"
  }
}

struct Dog: Codable {
  private(set) var type: String = "dog"
  var name: String
  var breed: String
}

enum Pet: Codable {
  case cat(Cat)
  case dog(Dog)

  private enum CodingKeys: String, CodingKey {
    case type
  }

  enum PetType: String, Codable {
    case cat
    case dog
  }

  init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    let type = try container.decode(PetType.self, forKey: .type)
    switch type {
    case .cat:
      self = .cat(try Cat(from: decoder))
    case .dog:
      self = .dog(try Dog(from: decoder))
    }
  }

  func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    switch self {
    case .cat(let obj):
      try container.encode(PetType.cat.rawValue, forKey: .type)
      try obj.encode(to: encoder)
    case .dog(let obj):
      try container.encode(PetType.dog.rawValue, forKey: .type)
      try obj.encode(to: encoder)
    }
  }
}

import typing
import pydantic
from typing_extensions import Annotated

class Cat(TypesyncModel):
    type: typing.Literal["cat"]
    name: str
    lives_left: int

class Dog(TypesyncModel):
    type: typing.Literal["dog"]
    name: str
    breed: str

Pet = Annotated[typing.Union[Cat, Dog], pydantic.Field(discriminator='type')]

function isValidCat(data) {
  return (
    (data is map) &&
    (data.keys().hasOnly(['type', 'name', 'lives_left'])) &&
    (data.type == 'cat') &&
    (data.name is string) &&
    (data.lives_left is int)
  );
}

function isValidDog(data) {
  return (
    (data is map) &&
    (data.keys().hasOnly(['type', 'name', 'breed'])) &&
    (data.type == 'dog') &&
    (data.name is string) &&
    (data.breed is string)
  );
}

function isValidPet(data) {
  return (isValidCat(data) || isValidDog(data));
}

`alias`

Represents an alias of another type.

User:
  model: alias
  type:
    type: object
    fields:
      name_first:
        type: string
      name_last:
        type: string

WorkspaceMember:
  model: alias
  type: User

export type User = {
  name_first: string;
  name_last: string;
};

export type WorkspaceMember = User;

struct User: Codable {
  var nameFirst: String
  var nameLast: String

  private enum CodingKeys: String, CodingKey {
    case nameFirst = "name_first"
    case nameLast = "name_last"
  }
}

typealias WorkspaceMember = User

class User(TypesyncModel):
    name_first: str
    name_last: str

WorkspaceMember = User

function isValidUser(data) {
  return (
    (data is map) &&
    (data.keys().hasOnly(['name_first', 'name_last'])) &&
    (data.name_first is string) &&
    (data.name_last is string)
  );
}

function isValidWorkspaceMember(data) {
  return isValidUser(data);
}

Overview

Schema

CLI Reference

`any`

`unknown`

`nil`

`string`

`boolean`

`int`

`double`

`timestamp`

`bytes`

`document-reference`

Parameterized form

`literal`

`enum`

`tuple`

`list`

`map`

`object`

Swift-specific options

`union`

`alias`

​any

​unknown

​nil

​string

​boolean

​int

​double

​timestamp

​bytes

​document-reference

​Parameterized form

​literal

​enum

​tuple

​list

​map

​object

​Swift-specific options

​union

​alias

`any`

`unknown`

`nil`

`string`

`boolean`

`int`

`double`

`timestamp`

`bytes`

`document-reference`

Parameterized form

`literal`

`enum`

`tuple`

`list`

`map`

`object`

Swift-specific options

`union`

`alias`