> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typesync.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: any
  ```

  ```ts models.ts theme={null}
  export type Example = any;
  ```

  ```swift models.swift theme={null}
  typealias Example = Any
  ```

  ```python models.py theme={null}
  import typing

  Example = typing.Any
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return true;
  }
  ```
</CodeGroup>

## `unknown`

Represents an unknown type.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: unknown
  ```

  ```ts models.ts theme={null}
  export type Example = unknown;
  ```

  ```swift models.swift theme={null}
  typealias Example = Any
  ```

  ```python models.py theme={null}
  import typing

  Example = typing.Any
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return true;
  }
  ```
</CodeGroup>

## `nil`

Represents the explicit absence of a value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: nil
  ```

  ```ts models.ts theme={null}
  export type Example = null;
  ```

  ```python models.py theme={null}
  Example = None
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return true;
  }
  ```
</CodeGroup>

## `string`

Represents a string value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: string
  ```

  ```ts models.ts theme={null}
  export type Example = string;
  ```

  ```swift models.swift theme={null}
  typealias Example = String
  ```

  ```python models.py theme={null}
  Example = str
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is string);
  }
  ```
</CodeGroup>

## `boolean`

Represents a boolean value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: boolean
  ```

  ```ts models.ts theme={null}
  export type Example = boolean;
  ```

  ```swift models.swift theme={null}
  typealias Example = Bool
  ```

  ```python models.py theme={null}
  Example = bool
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is bool);
  }
  ```
</CodeGroup>

## `int`

Represents a signed integer.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: int
  ```

  ```ts models.ts theme={null}
  export type Example = number;
  ```

  ```swift models.swift theme={null}
  typealias Example = Int
  ```

  ```python models.py theme={null}
  Example = int
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is int);
  }
  ```
</CodeGroup>

## `double`

Represents a double-precision floating point number.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: double
  ```

  ```ts models.ts theme={null}
  export type Example = number;
  ```

  ```swift models.swift theme={null}
  typealias Example = Double
  ```

  ```python models.py theme={null}
  Example = float
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is float);
  }
  ```
</CodeGroup>

## `timestamp`

Represents a datetime value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: timestamp
  ```

  ```ts models.ts theme={null}
  export type Example = firestore.Timestamp;
  ```

  ```swift models.swift theme={null}
  typealias Example = Date
  ```

  ```python models.py theme={null}
  import datetime

  Example = datetime.datetime
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is timestamp);
  }
  ```
</CodeGroup>

## `bytes`

Represents a Firestore bytes value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: bytes
  ```

  ```ts models.ts theme={null}
  // Firebase Web targets emit firestore.Bytes; React Native Firebase emits firestore.Blob.
  export type Example = Buffer;
  ```

  ```swift models.swift theme={null}
  typealias Example = Data
  ```

  ```python models.py theme={null}
  Example = bytes
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is bytes);
  }
  ```
</CodeGroup>

## `document-reference`

Represents a Firestore [document reference](https://firebase.google.com/docs/reference/js/firestore_.documentreference) — 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.

<Info>
  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.
</Info>

<Info>
  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.
</Info>

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type: document-reference
  ```

  ```ts models.ts theme={null}
  export type Example = firestore.DocumentReference<firestore.DocumentData>;
  ```

  ```swift models.swift theme={null}
  typealias Example = DocumentReference
  ```

  ```python models.py theme={null}
  Example = firestore.DocumentReference
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is path);
  }
  ```
</CodeGroup>

### 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.

<Info>
  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.
</Info>

<CodeGroup>
  ```yaml definition.yml theme={null}
  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
  ```

  ```ts models.ts theme={null}
  export interface Author {
    name: string;
  }
  export interface Book {
    title: string;
    author: firestore.DocumentReference<Author>;
  }
  ```

  ```python models.py theme={null}
  class Author(TypesyncModel):
      name: str
  class Book(TypesyncModel):
      title: str
      author: firestore.DocumentReference  # not narrowed; Python SDK class is not generic
  ```

  ```swift models.swift theme={null}
  struct Author: Codable {
      var name: String
  }
  struct Book: Codable {
      var title: String
      var author: DocumentReference  // not narrowed; iOS SDK class is not generic
  }
  ```
</CodeGroup>

## `literal`

Represents a literal type.

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

<CodeGroup>
  ```yaml definition.yml theme={null}
  MeaningOfLife:
    model: alias
    type:
      type: literal
      value: 42
  ```

  ```ts models.ts theme={null}
  export type MeaningOfLife = 42;
  ```

  ```swift models.swift theme={null}
  typealias MeaningOfLife = Int
  ```

  ```python models.py theme={null}
  import typing

  MeaningOfLife = typing.Literal[42]
  ```

  ```javascript firestore.rules theme={null}
  function isValidMeaningOfLife(data) {
    return data == 42;
  }
  ```
</CodeGroup>

## `enum`

Represents an enum value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  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
  ```

  ```ts models.ts theme={null}
  export type UserRole = 'owner' | 'admin' | 'member';
  ```

  ```swift models.swift theme={null}
  enum UserRole: String, Codable {
    case Owner = "owner"
    case Admin = "admin"
    case Member = "member"
  }
  ```

  ```python models.py theme={null}
  import enum

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

  ```javascript firestore.rules theme={null}
  function isValidUserRole(data) {
    return data == 'owner' || data == 'admin' || data == 'member';
  }
  ```
</CodeGroup>

## `tuple`

Represents a tuple value.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type:
      type: tuple
      elements:
        - string
        - boolean
        - int
  ```

  ```ts models.ts theme={null}
  export type Example = [string, boolean, number];
  ```

  ```swift models.swift theme={null}
  typealias Example = (String, Bool, Int)
  ```

  ```python models.py theme={null}
  Example = tuple[str, bool, int]
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return ((data is list) && (data[0] is string) && (data[1] is bool) && (data[2] is int));
  }
  ```
</CodeGroup>

## `list`

Represents a list of items.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type:
      type: list
      elementType: string
  ```

  ```ts models.ts theme={null}
  export type Example = string[];
  ```

  ```swift models.swift theme={null}
  typealias Example = [String]
  ```

  ```python models.py theme={null}
  Example = typing.List[str]
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is list);
  }
  ```
</CodeGroup>

## `map`

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

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type:
      type: map
      valueType: int
  ```

  ```ts models.ts theme={null}
  export type Example = Record<string, number>;
  ```

  ```swift models.swift theme={null}
  typealias Example = [String: Int]
  ```

  ```python models.py theme={null}
  import typing

  Example = typing.Dict[str, int]
  ```

  ```javascript firestore.rules theme={null}
  function isValidExample(data) {
    return (data is map);
  }
  ```
</CodeGroup>

## `object`

Represents an object with known fields.

<CodeGroup>
  ```yaml definition.yml theme={null}
  Example:
    model: alias
    type:
      type: object
      fields:
        name:
          type: string
        completed:
          type: boolean
        github_url:
          type: string
          optional: true
  ```

  ```ts models.ts theme={null}
  export type Example = {
    name: string;
    completed: boolean;
    github_url?: string;
  };
  ```

  ```swift models.swift theme={null}
  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"
    }
  }
  ```

  ```python models.py theme={null}
  # ...
  class Example(TypesyncModel):
      name: str
      completed: bool
      github_url: typing.Union[TypesyncUndefined, str] = UNDEFINED
  # ...
  ```

  ```javascript firestore.rules theme={null}
  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))
    );
  }
  ```
</CodeGroup>

### 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.

```yaml theme={null}
Example:
  model: alias
  type:
    type: object
    fields:
      class:
        type: string
        swift:
          name: userClass
```

```swift theme={null}
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**

<CodeGroup>
  ```yaml definition.yml theme={null}
  Path:
    model: alias
    type:
      type: union
      variants:
        - string
        - type: list
          elementType: string
  ```

  ```ts models.ts theme={null}
  export type Path = string | string[];
  ```

  ```swift models.swift theme={null}
  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)
      }
    }
  }
  ```

  ```python models.py theme={null}
  Path = typing.Union[str, typing.List[str]]
  ```

  ```javascript firestore.rules theme={null}
  function isValidPath(data) {
    return ((data is string) || (data is list));
  }
  ```
</CodeGroup>

**Discriminated Union Example**

<CodeGroup>
  ```yaml definition.yml theme={null}
  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
  ```

  ```ts models.ts theme={null}
  export type Cat = {
    type: 'cat';
    name: string;
    lives_left: number;
  };

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

  export type Pet = Cat | Dog;
  ```

  ```swift models.swift theme={null}
  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)
      }
    }
  }
  ```

  ```python models.py theme={null}
  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')]
  ```

  ```javascript firestore.rules theme={null}
  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));
  }
  ```
</CodeGroup>

## `alias`

Represents an alias of another type.

<CodeGroup>
  ```yaml definition.yml theme={null}
  User:
    model: alias
    type:
      type: object
      fields:
        name_first:
          type: string
        name_last:
          type: string

  WorkspaceMember:
    model: alias
    type: User
  ```

  ```ts models.ts theme={null}
  export type User = {
    name_first: string;
    name_last: string;
  };

  export type WorkspaceMember = User;
  ```

  ```swift models.swift theme={null}
  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
  ```

  ```python models.py theme={null}
  class User(TypesyncModel):
      name_first: str
      name_last: str

  WorkspaceMember = User
  ```

  ```javascript firestore.rules theme={null}
  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);
  }
  ```
</CodeGroup>