What are Schemas?

Schemas are one of the core pillars of Endgrate — when initiating a session, they are used to define exactly what format(s) of data you want to pull, push, or sync.

Every single integration provider works with data in different formats, and schemas are used to standardize the flow so that you can deal with data in the exact form you want. Endgrate automatically handles all of the data transformation across any integration provider.

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

Here's an example of a schema:

{
  "type": "object",
  "endgrate_type": "crm-contact",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "full_name": {
      "type": "string"
    },
    "company": {
      "type": "string"
    },
    "age": {
      "type": "number"
    },
    "is_employed": {
      "type": "boolean"
    },
    "lifecyclestage": {
      "title": "Lifecycle Stage",
      "type": "string"
    }
  },
  "required": [
    "email"
  ],
  "title": "Contact"
}

📘

Note

We recommend all schemas specify an endgrate_type. However, we provide the option for schemas to be representative of multiple types of data. Check out the guide here for a full explanation of how to use custom JSON schemas without an endgrate_type.

Using Multiple Schemas

Endgrate's initiate endpoints have the schema body parameter, which is where you specify the schema(s) that you want to deal with.

By default, Endgrate will consider all of the specified schemas as "active". In other words, we'll match all of the specified schemas to a corresponding resource (e.g. contacts, companies).

You can also specify the schema_selection flag to let your users choose which schemas are "active". That way, only a certain subset of resources will be eligible to push or pull.

When dealing with dynamic custom objects, you can specify the passthrough_schemas flag to let your users choose which custom objects are "active".

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.

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

1. The title, e.g. "Attribute Name. This is a human-readable name of the attribute, and Endgrate will display this title to your end user on certain configuration pages if it is provided.
2. The format, such as "uri" or "email" if the type is a string.
3. The properties, if the type is an object.
4. The items, if the type is an array.
5. A default value. Endgrate will fallback to this default value if it is provided.
6. An enum list. Endgrate will validate and ensure values for this attribute are in this list if it is provided.

JSON Schema Types

Endgrate supports a variety of attribute types defined in the JSON Schema standard spec that you can use when defining schemas. Endgrate will format data to meet the type requirements and will fallback on a default value if the formatting fails.

String

• Formatting: typecasting
• Return Type: string
• Default: ""
• Example Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

Number

• Formatting: typecasting
• Return Type: number (note: this may be a float value)
• Default: 0
• Example Schema:

{
  "type": "object",
  "properties": {
    "age": {
      "type": "number"
    }
  }
}

Boolean

• Formatting: typecasting
• Return Type: boolean
• Default: false
• Example Schema:

{
  "type": "object",
  "properties": {
    "is_employed": {
      "type": "boolean"
    }
  }
}

Email

• Formatting: specification
• Return Type: string
• Default: [email protected]
• Example Schema:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    }
  }
}

URI

• Formatting: specification
• Return Type: string
• Default: https://example.com
• Example Schema:

{
  "type": "object",
  "properties": {
    "website": {
      "type": "string",
      "format": "uri"
    }
  }
}

Date

• Formatting: "%Y-%m-%d", e.g. "2000-01-01", UTC
• Return Type: string
• Default: <current UTC date>
• Example Schema:

{
  "type": "object",
  "properties": {
    "birthday": {
      "type": "string",
      "format": "date"
    }
  }
}

Time

• Formatting: "%H:%M:%S", e.g. "00:00:00", UTC
• Return Type: string
• Default: <current UTC time>
• Example Schema:

{
  "type": "object",
  "properties": {
    "open_time": {
      "type": "string",
      "format": "time"
    }
  }
}

Date-Time

• Formatting: "%Y-%m-%d %H:%M:%S", e.g. "2000-01-01 00:00:00", UTC
• Return Type: string
• Default: <current UTC datetime>
• Example Schema:

{
  "type": "object",
  "properties": {
    "sale_datetime": {
      "type": "string",
      "format": "date-time"
    }
  }
}