Field definitions

Field definitions control the structure of a collection's documents.

collection Order {
  status: String? // Equivalent to `status: String | Null`
  cart: Array<{
    product: Ref<Product>?,
    quantity: Int?,
    price: Double?,
  }>?
  creationDate: Time = Time.now()
  deliveryAddress: {
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }?
  creditCard: {
    network: "Visa" | "MasterCard" | "American Express"?,
    number: String?,
  }?
}

Syntax

<fieldName>: <types>[ = <defaultValue>]

Name

fieldName String Required: Document field name.

Use a wildcard (*) definition to specify accepted data types for ad hoc fields. See Wildcard definitions.

Properties

Property Type Required Description

Property	Type	Required	Description
<types>	String	Yes	Accepted data types for the field. Separate multiple types by `\|`. Types must be persistable. Use `Any` to accept any persistable value. Use `Ref<CollectionName>` to accept a collection’s documents as a data type. Use the Union type to enumerate accepted field values. See Enumerated field values. The `?` (nullable) type annotation indicates the field accepts Null values. `?` is equivalent to `\| Null`. Fields that accept Null are not guaranteed to exist in every document of the collection.
<defaultValue>	String		Default field value. Used if the field is missing or the field value is `null`. Can be an FQL expression. The expression can have no effect other than to: Generate an ID, such as calling `ID()` or `newId()`. You must then cast the ID to a String using `toString()`. Get the current Date or Time, such as calling `Date.today()` or `Time.now()`. You can use a document as a default value. See Default to a document.

<types>

String

Yes

Accepted data types for the field. Separate multiple types by |.

Types must be persistable. Use Any to accept any persistable value. Use Ref<CollectionName> to accept a collection’s documents as a data type. Use the Union type to enumerate accepted field values. See Enumerated field values.

The ? (nullable) type annotation indicates the field accepts Null values. ? is equivalent to | Null.

Fields that accept Null are not guaranteed to exist in every document of the collection.

<defaultValue>

String

Default field value. Used if the field is missing or the field value is null.

Can be an FQL expression. The expression can have no effect other than to:

Generate an ID, such as calling ID() or newId(). You must then cast the ID to a String using toString().
Get the current Date or Time, such as calling Date.today() or Time.now().

You can use a document as a default value. See Default to a document.

Wildcard definitions

When you add field definitions to a collection, the collection’s documents can only contain the defined fields. To accept arbitrary ad hoc fields, add a wildcard (*) definition:

collection Order {
  // Only accept ad hoc fields with `String` or `Int` values
  *: String | Int
}

Ad hoc fields must conform to the wildcard definition’s accepted data types.

A collection can only have one wildcard definition. You can’t specify a default value for a wildcard.

Schemaless by default

If a collection has no field definitions, it implicitly accepts ad hoc fields of any type. This is equivalent to:

collection Order {
  // Contains no field definitions
  *: Any
}

This means the collection is schemaless. The collection’s documents can contain any field.

Flexible schema

If a collection has both field definitions and a wildcard definition, it has a flexible schema. The collection’s documents can contain ad hoc fields. However, fields must conform to the structure of their definitions.

collection Order {
  // Contains field definitions and a wildcard definition
  status: String?
  *: Any
}

Strict schema

If a collection has field definitions but doesn’t have a wildcard definition, it does not accept documents with ad hoc fields. This is called a strict schema or strict schema enforcement.

collection Order {
  // Contains no wildcard definition
  status: String?
}

Examples

Arrays

Use Array<…> to accept Array values:

collection Product {
  categories: Array<String>?
}

To accept an object array:

collection Customer {
  addresses: Array<{
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }>?
}

Default to today’s date

Use Date.today() to set today’s date as a default value:

collection Product {
  creationDate: Date = Date.today()
}

Default to the current time

Use Time.now() to set the current time as a default value:

collection Product {
  creationTime: Time = Time.now()
}

Default to a unique ID

Use newId() to use a unique ID as the default value. You must cast the ID to a String using toString():

collection Product {
  productId: String = newId().toString()
}

If used, Fauna generates a unique ID value for each document.

Default to a document

You can use a document as a backfill value:

collection Product {
  // Default `store` to a `Store` collection document.
  // Replace `400684606016192545` with a document ID.
  store: Ref<Store> = Store("400684606016192545")
}

Fauna doesn’t guarantee the document exists. You can’t fetch the document using an FQL expression.

Document relationships

Use Ref<CollectionName> to accept a collection’s documents as a data type:

collection Product {
  // Accepts `Store` collection documents and `null`
  store: Ref<Store>?
}

Documents may contain references to documents that don’t exist. These are called dangling references.

Enumerated field values

To accept enumerated values:

collection Customer {
  status: "silver" | "gold" | "platinum"?
}

Nested objects

To define a field containing a nested object:

collection Order {
  deliveryAddress: {
    street: String?,
    city: String?,
    state: String?,
    zipCode: String?,
  }?
}