Defining Custom Schemas

Here, we'll go over features and best practices to know when defining your own custom schemas.

As a reminder, schemas are defined using the JSON Schema Specification. If you are unfamiliar with the standard, here's a good introduction to how the standard works.

Special Cases

Naming Schemas

By default, Endgrate has straightforward built-in display names for schemas given their endgrate_type. For example, on configuration screens crm-contact is displayed as Contact and accounting-invoice is displayed as Invoice.

If you'd like to override this, specify a title for your schema.

{
  "endgrate_type": "crm-contact",
  "title": "Company Person",
  "type": "object",
  "properties": {...}
}

This is useful when you have multiple schemas with overlapping endgrate_types. When that is the case, the title is the unique identifier for the schema and should be used in place of endgrate_type in subsequent API calls to push or pull data.

The unspecified endgrate_type

unspecified is a special endgrate_type that encompasses all types of data. For example, if you have a dynamic resource that doesn't corresponding to any single endgrate_type, use this feature when defining your custom schema. You'll have to provide a title for the schema that you'll use in subsequent API calls to push or pull data.

{
  "endgrate_type": "unspecified",
  "title": "Data",
  "type": "object",
  "properties": {...}
}

JSON Schema Features

In its core, the JSON Schema standard obeys the following format:

"attribute_name": {
  "type": "attribute_type"
}

The key is the attribute name, and the value is an object that describe the properties of the attribute.

If the type is an object, Endgrate requires the properties to be present, and if the type is an array, Endgrate requires the items to be present.

In addition, you can specify other properties of the attribute that Endgrate will use, including:

  1. The title. This is a human-readable name of the attribute (we highly recommend including this). Endgrate will use this value to aid AI field mapping.
  2. The description. This is a human-readable description of the attribute (we highly recommend including this). Endgrate will use this value to aid AI field mapping.
  3. The format if the type is a string. We highly recommend including the format of a string if it is one we support. When the format is provided for an attribute, Endgrate will automatically format both incoming and outgoing data to meet the specification requirements. Endgrate supports the following formats:
    1. Email (email): specification, e.g. "[email protected]".
    2. URI (uri): specification, e.g. "https://endgrate.com".
    3. Date (date): "%Y-%m-%d", e.g. "2000-01-01", UTC.
    4. Time (time): "%H:%M:%S", e.g. "00:00:00", UTC.
    5. Date Time (date-time): "%Y-%m-%d %H:%M:%S", e.g. "2000-01-01 00:00:00", UTC.
  4. A default value. When a default value is provided for an attribute, Endgrate will automatically fallback to the default value in both incoming and outgoing data if the attribute does not exist.
  5. Enumeration values. Specifying this is useful when you want to restrict an attribute only to be within a fixed set of values.

If the type is an object, you can also specify the required property to enforce certain fields to be present. Endgrate will automatically skip data in both incoming and outgoing data if the attribute field(s) do(es) not exist.

Schema Attribute Examples

{
  "first_name": {
    "type": "string",
    "title": "First Name",
    "description": "The first name of the contact"
  }
}
{
  "email_address": {
    "type": "string",
    "format": "email"
  }
}
{
  "shirt_size": {
    "type": "string",
    "anyOf": [
      {
        "const": "S",
        "title": "Small",
        "description": ""
      },
      {
        "const": "L",
        "title": "Large",
        "description": ""
      }
    ]
  }
}
{
  "my_object": {
    "type": "object",
    "properties": {
      "a": {
        "type": "string"
      },
      "b": {
        "type": "string"
      }
    },
    "required": [
      "a"
    ]
  }
}