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 Structure

Type

Default

Notes

{

is:

string

required*

The name of the Type of this Field.

client:

boolean

true**

Indicates if this field should be serialized in toClient()/fromClient() calls. See client below.

custom:

boolean

Indicates if this field is a dynamic custom field that should have UI auto-generated for it.

aux:

boolean

false

Indicates that this field is auxiliary and should not be stored in the database. See Auxiliary Data.

db:

boolean

true**

Indicates if this field should be stored in the database.

historical:

boolean

none

Indicates that this field is historical. Must also be set on the collection to take effect. Only valid for top-level fields.

defaultValue:

any

none

Default value for this field. If a function, the default will be the return value of the function.

if:

object | async? opts => (object | boolean)****

none

Indicates this is a conditional field.

generated:

boolean

true if get...() is defined but not set...()

Indicates this is a computed field.

readonly:

boolean

true if generated

Indicates this is readonly field.

width:

integer

This provides the default width in pixels for this field when displayed in a table.

User Documentation

label:

string

labelify(name)

The human-readable label for this field.

pathLabel:

string

label

The label to use for this field when it is part of a path label.

help:

string

none

Contains brief user-facing documentation about this field (suitable for a tooltip).

placeholder:

string

none

Sets the default placeholder for this field to be used in input fields.

Developer Documentation

deprecated:

string

none

Indicates that this field is deprecated; the string should include the reason why it is deprecated and alterate approaches to use.

note:

string

none

Contains developer-facing documentation about this field (only visible in the Tyranid console).

Validation

required:

boolean

false

Indicates that this field is required.

validate:

async? field: Field => string?****

none

Specifies 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 Def

none

Indicates 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 name

none

Indicates 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:

boolean

false

Indicates if the bitmask should be inversed when stored.

Links (is == 'link')

denormal:

object

none

A Denormalization expression to populate when saving this field.

link:

collection name

none

Indicates 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****

none

Contains additional constraints on the links -- see links.

Numbers (is == 'double' || is == 'integer')

in:

string

none

Sets the units for this field (i.e. in: 'km'). See Units.parse.

min:

number

none

Sets the minimum value for this numeric field.

max:

number

none

Sets the maximum value for this numeric field.

step:

number

none

Indicates 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 Def

Specifies the type of the keys for this map.

of:

Field Def

required***

Indicates the type of the object's contents.

Query (is == 'query')

collection:

collection name

none

Indicates 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[] }

false

Set 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:

RegExp

none

Set this to a regular expression that the string must match.

minlength:

integer

none

Sets the minimum length of this string.

maxlength:

integer

none

Sets the maximum length of this string.

dynamicFieldName:

string

none

This 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?

none

Sets 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 names

Constrains 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)****

none

Indicates this is a computed property. Isomorphic get.

getClient:

() => any (based on is)****

none

A client-specific get function.

getServer:

() => any (based on is)****

none

A server-specific get function.

set:

() => void****

none

Specifies a set function for this field. Isomorphic set.

setClient:

() => void****

none

A client-specific set function.

setServer:

() => void****

none

A 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:

Value	Serialize 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.
undefined	Yes by default if not a computed value; no by default if a computed value (can be requested in a projection).
function	If 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?,

opts?: { labelField?: 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.

If the labelField option is specified then the given field will be used as the label.

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.

Overview

API

Tyreant

Field

Field Shorthand Syntax

Link Shorthand Syntax

client option