Schema Types

Realm is now Atlas Device SDK – Learn More

All Schema Types

The following fields are available for all BSON schemas regardless of type:

{
  "bsonType": "<BSON Type>" | ["<BSON Type>", ...],
  "type": "<JSON Type>" | ["<JSON Type>", ...],
  "enum": [<Value 1>, <Value 2>, ...],
  "description": "<Descriptive Text>,
  "title": "<Short Description>"
}

Field Name	Description
`bsonType`	The BSON type of the property the schema describes. If the property's value can be of multiple types, specify an array of BSON types. Cannot be used with the `type` field. BSON types include all JSON types as well as additional types that you can reference by name: `double` `string` `object` `array` `objectId` `date` `bool` `null` `regex` `int` `timestamp` `long` `decimal` `uuid` `binData` `mixed`
`type`	The JSON type of the property the schema describes. If the property's value can be of multiple types, specify an array of JSON types. Cannot be used with `bsonType`. Important Atlas App Services supports the `type` field to maintain compatibility with the JSON schema standard. However, we recommend that you use the `bsonType` field instead. BSON types include all JSON schema types and support even more data types. The following standard JSON types are available: `object` `array` `number` `boolean` `string` `null` Note MongoDB's JSON Schema implementation does not support the `integer` JSON type. Instead, use the `bsonType` field with `int` or `long` as the value.
`enum`	An array that includes all valid values for the data that the schema describes.
`title`	A short title or name for the data that the schema models. This field is used for metadata purposes only and has no impact on schema validation.
`description`	A detailed description of the data that the schema models. This field is used for metadata purposes only and has no impact on schema validation.

BSON Types

Array

An array contains multiple values of a specific type. BSON array schemas use the standard JSON Schema array format.

{
  "bsonType": "array",
  "items": <Schema Document> | [<Schema Document>, ...],
  "additionalItems": <boolean> | <Schema Document>,
  "maxItems": <integer>,
  "minItems": <integer>,
  "uniqueItems": <boolean>
}

Field Name	Description
`items`	A schema for all array items, or an array of schemas where order matters.
`additionalItems`	Default: `true`. If `true`, the array may contain additional values that are not defined in the schema. If `false`, only values that are explicitly listed in the `items` array may appear in the array. If the value is a schema object, any additional fields must validate against the schema. Note The `additionalItems` field only affects array schemas that have an array-valued `items` field. If the `items` field is a single schema object, `additionalItems` has no effect.
`maxItems`	The maximum length of the array.
`minItems`	The minimum length of the array.
`uniqueItems`	Default: `false` If `true`, each item in the array must be unique. If `false`, multiple array items may be identical. Tip Unique Arrays are Sets To model a Set, use the `array` schema type with `uniqueItems` set to `true`.

Boolean

A bool is either true or false.

{ "bsonType": "bool" }

Mixed

A mixed field may contain any schema type except for arrays, embedded objects, sets, and dictionaries. App Services does not enforce a consistent type across documents, so two different documents may have values of different types.

Mixed fields can represent relationships. Sync translates these relationships to MongoDB as a DBRef to preserve the database name, collection name, and primary key of the link.

{ "bsonType": "mixed" }

Number

A number generically configures some type of number. BSON schemas extend JSON Schema numerics with additional types to define integers, floats, and decimals.

{
  "bsonType": "number" | "int" | "long" | "double" | "decimal",
  "multipleOf": <number>,
  "maximum": <number>,
  "exclusiveMaximum": <boolean>,
  "minimum": <number>,
  "exclusiveMinimum": <boolean>
}

Field Name	Description
`multipleOf`	An integer divisor of the field value. For example, if `multipleOf` is set to `3`, `6` is a valid value but `7` is not.
`maximum`	The maximum value of the number.
`exclusiveMaximum`	Default: `false` If `true`, the field value must be strictly less than the `maximum` value. If `false`, the field value may also be equal to the `maximum` value.
`minimum`	The minimum value of the number.
`exclusiveMinimum`	Default: `false` If `true`, the field value must be strictly greater than the `minimum` value. If `false`, the field value may also be equal to the `minimum` value.

Object

An object is a structured object with string keys that each have a typed value. Objects represent Realm objects and embedded objects in synced realms as well as the documents they map to in MongoDB.

{
  "bsonType": "object",
  "title": "<Type Name>",
  "required": ["<Required Field Name>", ...],
  "properties": {
    "<Field Name>": <Schema Document>
  },
  "minProperties": <integer>,
  "maxProperties": <integer>,
  "patternProperties": {
    "<Field Name Regex>": <Schema Document>
  },
  "additionalProperties": <boolean> | <Schema Document>,
  "dependencies": {
    "<Field Name>": <Schema Document> | ["<Field Name>", ...]
  }
}

Field Name	Description
`required`	An array of field names that must be included in the document.
`title`	A type name for the object. App Services uses this value to name the document's type in the GraphQL API. (GraphQL is deprecated. Learn More)
`properties`	An object where each field maps to a field in the parent object by name. The value of each field is a schema document that configures the value of the field.
`minProperties`	The minimum number of fields allowed in the object.
`maxProperties`	The maximum number of fields allowed in the object.
`patternProperties`	An object where each field is a regular expression string that maps to all fields in the parent object that match. The value of each field is a schema document that configures the value of matched fields.
`additionalProperties`	Default: `true`. If `true`, a document may contain additional fields that are not defined in the schema. If `false`, only fields that are explicitly defined in the schema may appear in a document. If the value is a schema object, any additional fields must validate against the schema.
`dependencies`	Specify property and schema dependencies.

Note

Model Dictionaries With the object Schema Type

To model dictionaries, use the object schema type with additionalProperties set to the object type of the values stored in the dictionary.

ObjectId

An objectId is a 12-byte identifier for BSON objects. ObjectId values are most commonly used as the unique _id values of documents in a MongoDB collection or objects in a synced realm.

{ "bsonType": "objectId" }

String

A string is text encoded as a series of characters. BSON string schemas use the standard JSON Schema string format.

{
  "bsonType": "string",
  "maxLength": <integer>,
  "minLength": <integer>,
  "pattern": "<Regular Expression>"
}

Field Name	Description
`maxLength`	The maximum number of characters in the string.
`minLength`	The minimum number of characters in the string.
`pattern`	A regular expression string that must match the string value.

UUID

A uuid (Universal Unique Identifier) is a standardized 16-byte unique object identifier.

{ "bsonType": "uuid" }

Binary Data

A binData is a piece of unstructured binary data. Maps to the binary BSON type. Always uses subtype 0.

{ "bsonType": "binData" }

Realm Database Types

Set

A set is a collection of unique values.

A set schema is an array schema where uniqueItems is set to true.

{
   "bsonType": "array",
   "uniqueItems": true,
   "items": {
      "bsonType": "long"
   }
}

Dictionary

A dictionary is a collection of dynamic and unique string keys paired with values of a given type. A dictionary is functionally an object or document without pre-defined field names.

A dictionary schema is an object schema where properties is not defined and the value of additionalProperties is a schema for the dictionary value's type.

Dictionary of a BSON Type

To store a dictionary with values of a BSON type, set additionalProperties to the type's schema.

{
   "bsonType": "object",
      "additionalProperties": {
         "bsonType": "string"
      }
   }
}

Dictionary of Mixed BSON Types

To store a dictionary with mixed values, set additionalProperties to true:

{
   "bsonType": "object",
      "additionalProperties": true
   }
}

Alternatively, you can define a full mixed schema:

{
   "bsonType": "object",
      "additionalProperties": {
         "bsonType": "mixed"
      }
   }
}

Dictionary of Embedded Objects

To store a dictionary with embedded object values, define an object schema with the title field set to the embedded object's type name:

{
   "bsonType": "object",
      "additionalProperties": {
         "bsonType": "object",
         "title": “Address”,
         "properties": {
           "streetNumber": { "bsonType": "string" },
           "street": { "bsonType": "string" },
           "city": { "bsonType": "string" },
           "province": { "bsonType": "string" },
           "country": { "bsonType": "string" },
           "postalCode": { "bsonType": "string" }
         }
   }
}

Geospatial Data

Geospatial data describes points and other data on the earth's surface. App Services does not have built-in geospatial types. Instead, you model geographic data using standard GeoJSON objects.

If you are not using Device Sync, you can query your geospatial data with regular geospatial operators. However, if you are using Device Sync, there are additional requirements in how you store and query the data.

GeoJSON Point

A GeoJSON Point (GeoPoint) is a single location on the Earth's surface. The GeoPoint schema must a required type field, of type string, which is always set to "Point".

You must also provide a coordinates field, which is an array of doubles. The coordinates array must contain at least 2 double values, and may contain a third:

The first double is the longitude of the point, between -180 and 180.
The second is the latitude, between -90 and 90.
The optional third value represents the elevation/altitude of the point, in meters. Atlas ignores this value when performing queries.

Note

You cannot set an array as required in a Device Sync schema, so the Sync server checks that the coordinates field is present and meets the requirements.

To store a GeoPoint in Atlas for later querying with Atlas Device Sync, the following rules also apply to the GeoPoint object:

It must be of type object.
It must be embedded within another type.
Additional values are allowed within the coordinates array, as long as they are doubles.
Additional properties in the GeoPoint object are also allowed.

The following is the Device Sync schema of an object with an embedded GeoPoint property named "location":

{
  "title": "MyObject",
  "properties": {
     "_id": {
       "bsonType": "objectId"
     },
     "location": {
       "bsonType": "object",
       "required": [ "type" ],
       "properties": {
         "type": {
           "bsonType": "string",
         },
         "coordinates": {
           "bsonType": "array",
           "items": {
             "bsonType": "double"
           }
         }
       }
     }
   }
}

The following code block shows a document that follows the schema. It has a single embedded GeoPoint object named "location".

{
  "_id": { "$oid": "65039d09fe4e46dddee31a3f" },
  "location": {
    "type": "Point",
    "coordinates": [-122.4, 48.12, 23.0]
   }
}

GeoJSON Points and Device Sync Queries

GeoPoints are the only form of geospatial data that Device Sync can query. The Device Sync server validates every embedded GeoPoint property with the rules outlined above.

If a device writes an object that fails validation, it will be reverted with a compensating write error. If a document that doesn't meet these requirements is written directly to the MongoDB collection, the server marks that document as unsyncable.

Querying

You can query a GeoPoint using Realm Query Language (RQL), using geoWithin to do so. Although GeoPoints are the only stored type you can query, your query may contain other geospatial types. For example, this partial query looks for all points within the specified GeoCircle:

location geoWithin GeoCircle([-73.981209, 40.725055], 0.00050464271)

For SDK-specific details about querying against geospatial data, see:

← Remove a Schema

Relationships →

Schema Types.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

All Schema Types

Important

Note

BSON Types

Array

Note

Tip

Unique Arrays are Sets

Boolean

Mixed

Number

Object

Note

Model Dictionaries With the object Schema Type

ObjectId

String

UUID

Binary Data

Realm Database Types

Set

Dictionary

Dictionary of a BSON Type

Dictionary of Mixed BSON Types

Dictionary of Embedded Objects

Geospatial Data

GeoJSON Point

Note

GeoJSON Points and Device Sync Queries

Querying

Schema Types