The Custom Objects API lets you create object records that are based on a blueprint -- or schema -- that you design yourself. A schema defines the named properties of a custom object. The schema doesn't contain information about any specific object. It just describes the information.

You can also define validation rules in the schema to maintain the data integrity of your object records.

A schema in the Custom Objects API is based on the JSON Schema specification. For more information, see the following resources on json-schema.org:

Understanding schemas in the Custom Objects API

A schema is a template for creating and validating object records of a certain type. The following example is one possible schema for fitness classes:

Name Type Required Description
id string yes Unique identifier assigned to the fitness class
name string yes Friendly public name for the fitness class
size number no Maximum number of people allowed to take the class

A schema consists of keyword/value pairs in a JSON object. Keywords are schema properties defined in the JSON Schema specification. Custom objects support the following keywords:

  • title
  • description
  • properties
  • type
  • items
  • required

You define the schema as part of creating an object type with the Custom Objects API. The following example shows the JSON payload to create an object type.

{  "data": {    "key": "fitness_class",    "schema": {      "properties": {        "id": {          "type": "string",          "description": "Unique identifier assigned to the fitness class"        },        "name": {          "type": "string",          "description": "Friendly public name for the fitness class"        },        "size": {          "type": "number",          "description": "Maximum number of people allowed to take the class"        }      },      "required": ["id", "name"]    }  }}

The example uses the following JSON Schema keywords: "properties", "type", "description", and "required".

Defining properties of your custom object

You can define any property you want for your custom object based on the JSON Schema specification, subject to the exceptions described in this section.

A typical property definition consists of a property name and an object with the "type" keyword from JSON Schema.

"schema": {  "properties": {    "exercise_room": {      "type": "string"    }  }}

There's no standard convention for schema property names. Using snake_case or camelCase is common. The names appear in the JSON body of HTTP responses from the Custom Objects API so use what makes sense for the application that will consume the data.

For custom objects, the following naming rules apply for properties:

  • You can't start a name with an underscore ("_")
  • You can't use an asterisk ("*") as a name
  • You can't use any of the following escape characters: "\b", "\f", "\n", "\r", "\t", "\u0007", "\u0013"

In the JSON Schema, the properties of an object are not restricted to the ones in the schema. For custom objects however, the properties are restricted to the ones in the schema. If the Custom Objects API receives a request to create or update an object record with a property not in the schema, the API returns a "422 Unprocessable Entity" status. The response specifies that the request has a property that's not allowed by the schema. If you try to override this behavior by using "additionalProperties": true in the schema, the API returns a 400 Bad Request error.

The JSON Schema supports not defining any properties at all in the schema. For custom objects however, the schema must define at least one property.

Specifying required properties

By default, all the properties defined by a schema are optional. You'll probably need at least one or more required properties for your custom object. A typical example of a required property is a record id or name.

Use the "required" keyword to specify one or more required properties for an object. The keyword takes an array of property names. Example (highlighted):

"schema": {  "properties": {    "name": { "type": "string" },    "email": { "type": "string" },    "address": { "type": "string" }  },  "required": ["name", "email"]}

If the Custom Objects API receives a request to create a record without providing a required property, the API returns a "422 Unprocessable Entity" status. The response specifies that the request has a missing property.

Validating the data type of a property

You can use the "type" keyword in your schema to validate data when creating or updating a record of that object type. The API only creates or updates a record if the value provided for the property matches the declared data type.

"schema": {  "properties": {    "num_locations": {       "type": "number"    }    }  }

For example, if you specify a string for a property that expects an array, the API returns a "422 Unprocessable Entity" status. The response specifies that the request has a property that doesn't match the allowed type.

The "type" can be one of the following:

  • string - a Unicode string
  • integer - an integral number
  • number - any numeric type, either integers or floating point numbers
  • array - an ordered list of values
  • boolean - true or false

The null and object types are not supported for custom objects.

For custom objects, you can specify only one type for a property. In the JSON Schema, you can specify more than one type by specifying an array of supported types such as "type": ["string", "number"].

If you don't want to perform any data validation at all, don't specify a type for the property:

"schema": {  "properties": {    "num_locations": {}  }  }

In that case, the API will accept any data type for the property.

Exception: When defining a property of type array, you must include an items element that defines the type of the items in the array. The type of the items can be boolean, integer, number, or string.

{  "type": "array",  "items": {    "type": "number"  }}

Validating strings

You can validate whether a string is too long or too short. You can also validate a string against a regular expression to make sure it follows a specific format, such as the format for an email address or phone number.

The property's type must be declared as a "string".

To validate the length of a string, use the "minLength" and "maxLength" keywords. Example:

"properties": {  "exercise_room": {     "type": "string",     "minLength": 3,     "maxLength": 18  }}

If the Custom Objects API receives a request to create or update a record with a string that's too long or too short, the API returns a "422 Unprocessable Entity" status. The response specifies that the string is too long or too short.

To validate a string against a regular expression, use the "pattern" keyword. Example:

"properties": {  "phone_number": {     "type": "string",     "pattern": "^(\([0-9]{3}\))?[0-9]{3}-[0-9]{4}$"  }}

If the Custom Objects API receives a request to create or update a record with a string that doesn't match the pattern, the API returns a "422 Unprocessable Entity" status. The response specifies that the regex does not match the input string.

Restricting a property to a fixed set of values

You may want to restrict a property value to a small set of possible values. For example, you might want the value of a "status" property to be one of "planned", "started", or "done".

Use the "enum" keyword to restrict the possible value of a property to a fixed set of values.

"status": {   "type": "string",   "enum": ["planned", "started", "done"]}

If the Custom Objects API receives a request to create or update a record with a value that's not one of the possible values, the API returns a "422 Unprocessable Entity" status. The response specifies that the string was not found in the enum.

Restricting a number to a range of values

You can use the "minimum" and "maximum" keywords to specify a range of accepted values for a property of type number. In the following example, the value of the property can be any number between 0 and 30, inclusive.

"properties": {  "num_weeks": {     "type": "number",     "minimum": 0,     "maximum": 30  }}

To exclude the starting or ending range value, use "exclusiveMinimum" or "exclusiveMaximum".

If the Custom Objects API receives a request to create or update a record with a number that's outside the range, the API returns a "422 Unprocessable Entity" status. The response specifies that the number is lower than the required minimum or higher than the required maximum.

Annotating your schema

You can annotate the schema for others who might use or edit the schema. The annotations can also form the basis of developer docs you create for your custom object.

You can use any combination of the following keywords to annotate a schema:

  • title - short description
  • description - longer explanation about the purpose of the data

None of the keywords are required and the information has no effect on validating data.

Example:

"distance": {  "type": "number",  "title" : "Race distance",  "description": "Bicycle race distance in kilometers"}

The information will be available to anybody who retrieves the object type with the Custom Objects API.

Note: The Custom Objects API doesn't currently support "examples" keyword from the JSON Schema.