Field

$metaType: 'field'

This returns 'field'.

aux: boolean

This returns true if this is an auxiliary field (i.e. not stored in the database).

Not all fields not stored in the database are auxiliary. Computed fields by default are not stored in the database and are not auxiliary.

collection: Collection

The collection that this field belongs to.

computed: boolean

This property is true if the field has a getter defined but no setter.

For example, _id is generated but not computed.

db: boolean

This returns true if this field is persisted in the database.

def

This defines the structure of a field and is the argument that is passed into the Field constructor (however, you do not need manually call the Field constructor -- it will be called on your behalf as the Collection def is parsed).

Only a subset of the following information is available on the client. Collections not marked client: true are not available on the client at all. Fields not marked client: true are also not available. Server-side functions are not available on the client. In general, the client only has data needed by the client to do things like construct form fields and do validation, and so on ... i.e. on a need-to-know basis.

Object StructureTypeDefaultNotes
{
is:stringrequired*The name of the Type of this Field.
client:booleantrue**Indicates if this field should be serialized in toClient()/fromClient() calls. See client below.
custom:booleanIndicates if this field is a dynamic custom field that should have UI auto-generated for it.
aux:booleanfalseIndicates that this field is auxiliary and should not be stored in the database. See Auxiliary Data.
db:booleantrue**Indicates if this field should be stored in the database.
historical:booleannoneIndicates that this field is historical. Must also be set on the collection to take effect. Only valid for top-level fields.
defaultValue:anynoneDefault value for this field. If a function, the default will be the return value of the function.
if:object | async? opts => (object | boolean)****noneIndicates this is a conditional field.
generated:booleantrue if get...() is defined but not set...()Indicates this is a computed field.
readonly:booleantrue if generatedIndicates this is readonly field.
width:integerThis provides the default width in pixels for this field when displayed in a table.
User Documentation
label:stringlabelify(name)The human-readable label for this field.
pathLabel:stringlabelThe label to use for this field when it is part of a path label.
help:stringnoneContains brief user-facing documentation about this field (suitable for a tooltip).
placeholder:stringnoneSets the default placeholder for this field to be used in input fields.
Developer Documentation
deprecated:stringnoneIndicates that this field is deprecated; the string should include the reason why it is deprecated and alterate approaches to use.
note:stringnoneContains developer-facing documentation about this field (only visible in the Tyranid console).
Validation
required:booleanfalseIndicates that this field is required.
validate:async? field: Field => string?****noneSpecifies a function that can perform custom validation. If a validation error occurs, the function should return a string with a human-readable explanation for the message. Alternatively the function can throw a UserError.
Arrays (is == 'array')
of:Field DefnoneIndicates the type of the array.
cardinality:integer .. integer | '*'0..*Indicates the cardinality of the array. For example, "1..3" means the array can have between 1 and 3 entries.
numbering:Numbering'uppercase'Specifies how array indices should be displayed in user interfaces.
Bitmasks (is == 'bitmask')
link:collection namenoneIndicates that this field contains foreign keys to the given collection. This must be a static collection not containing more than 53 entries (Math.log2(Number.MAX_SAFE_INTEGER) == 53).
inverse:booleanfalseIndicates if the bitmask should be inversed when stored.
Links (is == 'link')
denormal:objectnoneA Denormalization expression to populate when saving this field.
link:collection namenoneIndicates that this field contains foreign keys to the given collection.
relate:'owns' | 'ownedBy' | 'associate''associate'Indicates the relationship conveyed by the link.
where:object | async? opts => object****noneContains additional constraints on the links -- see links.
Numbers (is == 'double' || is == 'integer')
in:stringnoneSets the units for this field (i.e. in: 'km'). See Units.parse.
min:numbernoneSets the minimum value for this numeric field.
max:numbernoneSets the maximum value for this numeric field.
step:numbernoneIndicates the step-size for this numeric field. This can be a non-integer value for double types (i.e. 0.001).
Integers (is == 'integer')
numbering:Numbering'integer'Specifies the numbering system used to display positive integers.
Objects (is == 'object')
Structured Object
fields: {Specifies the structure of a nested object.
fieldName:Field Def
...
},
Map Object
keys:Field DefSpecifies the type of the keys for this map.
of:Field Defrequired***Indicates the type of the object's contents.
Query (is == 'query')
collection:collection namenoneIndicates that this contains a query against the given collection. If not specified this represents a query against the current collection that this field is assigned to.
S3 (is == 's3')
of:array of media types*Set this to the list of valid media types that can be stored in this field. Specify "*" to indicate all media types are valid or "registry/*" where registry is a valid media type registry tree (i.e. 'application', 'audio', 'font', 'text', 'video', ...)
Strings (is == 'string')
labelField:boolean |
{ uses: string[] }
falseSet to true if this field contains the label for this collection.

If the uses options object is specified, then the array of strings should contain a list of fields that are needed to properly display labels. A common example would be if you want an image URL to show for a portrait next to labels -- you could indicate that the label uses the image field. This would cause methods like labels() and so on to also query in the image field.

pattern:RegExpnoneSet this to a regular expression that the string must match.
minlength:integernoneSets the minimum length of this string.
maxlength:integernoneSets the maximum length of this string.
dynamicFieldName:stringnoneThis is used to indicate that this string contains the name of a dynamic field that has a link to the collection that this string property is attached to. This is used to create a common lookup table that different dynamic link fields can share.
Time (is == 'date' || is == 'datetime')
granularity:
integer?'year' |
'month' |
'day' |
'hour' |
'minute' |
'second' |
'millisecond'
noneSets the granularity for this time field. The optional number indicates the multiple of the granularity (the default multiple is 1). For example, "30 minutes" would mean that the user can select, say 2:00, or 2:30, but not 2:35.

Granularities are restricted by the underlying type. For example, datetime can have minute granularity but date cannot.

UIDs (is == 'uid')
of:collection namesConstrains the type of UIDs that can be stored in this UID field. Collection names can be an array of names or a single name.
Computed Properties
get:() => any (based on is)****noneIndicates this is a computed property. Isomorphic get.
getClient:() => any (based on is)****noneA client-specific get function.
getServer:() => any (based on is)****noneA server-specific get function.
set:() => void****noneSpecifies a set function for this field. Isomorphic set.
setClient:() => void****noneA client-specific set function.
setServer:() => void****noneA server-specific set function.
}
* is is not required if link is specified -- the type is inferred to be link in that case.
** client and db usually defaults to true except for computed properties (you can still set client: true and/or db: true for computed properties, they just don't default to true).
*** of is required if keys is specified.
**** The current document is passed as this.

Field Shorthand Syntax

A field shortcut syntax is available. For example,

the following:is equivalent to:
name: 'string' name: { is: 'string' }

Link Shorthand Syntax

If you pass in a Collection instance in various places in a field definition it will infer that a link to that collection should be assumed. For example,

the following:are all equivalent to:
job: Job
job: { is: Job }
job: { link: Job } }
job: { link: 'job' }

Similarly,

the following:are all equivalent to:
jobs: { is: 'array', of: Job }
jobs: { is: 'array', of: { link: Job } }
jobs: { is: 'array', of: { link: 'job' } }

and so on. Be careful when using this syntax with cyclic imports as it can result in bootstrapping error about an undefined field.

client option

The client option indicates if this field should be serialized in toClient()/fromClient() calls. It can take on the following values:

ValueSerialize in toClient() ?
true, 1, 'default'Yes by default.
false, 0, 'never'No, not even if requested in a projection.
'conditional'No, unless requested in a projection.
undefinedYes by default if not a computed value; no by default if a computed value (can be requested in a projection).
functionIf client is a function the function will be invoked and its result should be one of the values in this table. It will be invoked as follows:
client function.call(document, value to be serialized, opts passed to toClient(), final merged projection)
dynamicMatch: object

If this is a dynamic field, then this will be set to the value of the dynamic schema's match property.

fields: { field name: Field }

This is a parallel hash to def.fields that contains the generated Field objects if this is of type === 'object'.

format(value: any): any

Formats a value according to the field and type suitable for display.

fromClient(value: any): any

This method will be used by Tyranid to convert incoming data from the client into server objects. For example, MongoId types will convert client-side MongoID strings into server-side ObjectId objects.

generated: boolean

This property is true if the field is generated. For example, if it has a getter defined but no setter.

A field might also be generated even if it does not have a getter defined. A field can be marked generated manually if the field is managed by code rather than via user-input.

group: string

This contains the name of the group this field is in if it is part of a field group.

in: Units

This returns the Units for this field if they were specified.

isMethod(): boolean

This returns true if this a parameter or return value definition for part of a service method.

keys: Field

This is only valid on objects and it indicates that the object is a key/value map rather than an object with predefined fields.

keys specifies the type of the keys (usually a string or uid type).

If keys is present, then of must be specified as well to define the contents of the map.

For example, the following defines an object with string keys and integer values:

{
  is: 'object',
  keys: 'string',
  of: 'integer'
}

See Maps for more information.

label: string

This returns a label, or display name, for the field.

labelify(value): any

If this field is a link and the value is a link value, then this method will return appropriate label. Otherwise the input value will be returned untouched.

labels(doc: Document, text: string?): { _id: id type, label field: string }[]

This generates a list of label objects that can be used to populate a typeahead dropdown. This method is only available when the field is a link or uid field.

This method also takes into account the where property on links when generating the list of labels.

link: Collection

This returns the Collection for this field if it is of type link.

methodName: string

This returns the name of the method if this a parameter or return value definition for part of a service method.

name: string

This contains the name of this field.

numbering: Numbering

This contains the numbering for this integer or array (indices) field when displayed in the user interface. For example, should array indices be numbered 0, 1, 2, 3 or I, II, III, IV, and so on.

of: Field (arrays and maps)
of: Collection[] (UIDs)

This returns the link Field for the contents of this array or map object.

If this field is of type "uid", then this will contain an array of collections that this UID must be constrained to.

parent: Field

This returns the parent field or null if this is a root field.

path: Path

This returns a Path for this field.

pathLabel: string

This contains the full path label for this field.

pathName: string

This contains the path of this field.

readonly: boolean

This property is true if the field is readonly. For example, if it is computed.

relate: 'associate' | 'owns' | 'ownedBy'

This returns the relationship of a link field.

spath: string

This contains the simplified path of this field.

This is a short-cut for this.path.spath.

Also see Paths for more information.

toClient(value: any): any

This method will be used by Tyranid to convert server data into JSON suitable for the client. For example, MongoId types will convert server-side ObjectIds into client-side MongoID strings.

type: Type

This returns the Type for this field.

validate(doc: Document): void throws UserError

This applies any validate function defined in the Field.def and throws a UserError if a validation error occurred.

width?: number

This returns the default with for this field when displayed in a table.