Schema Properties

High-level overview of JSON Schemas returned from Merge

Schema Properties

High-level overview of JSON Schemas returned from Merge

Overview

Merge uses JSON Schema conventions in schemas returned from Merge (e.g., the request_schema returned from a /meta endpoint) for scalable schemas and programmatic convenience.

In these schemas:

Shared Properties specify type definitions with fields like “type” and “description”
Object, Array and Enum Fields will have additional schema properties as described further below

For example, when you receive a request_schema from a /meta endpoint, the schema fields specify valid inputs in a POST request to Merge. Learn more in our guide to Programmatic Writes with /meta.

For programmatic validation of these schema properties, we encourage you to refer to the JSON Schema specification.

Shared Properties

All fields in JSON Schemas returned from Merge have basic properties like “type” and “description” that specify field types.

Property	Type	Description
`type`	string	Denotes the type of data stored in this field.
`description`	string	If available, will explain what data is expected.

Object Fields

In addition to shared properties, object fields in JSON Schemas returned from Merge will have these additional properties:

Property	Type	Description
`properties`	object	Denotes the object’s key-value pairs where the key is the field name and the value is the sub-schema of the field.
`required`	array	Denotes which object fields are required or optional when making a POST request.

Array Fields

In addition to shared properties, array fields in JSON Schemas returned from Merge will have these additional properties:

Property	Type	Description
`items`	object	`items` is an object describing the `type` and `properties` of the items of the array.

Enum Fields

In addition to shared properties, enum fields that have a limited array of string choices will have these additional properties:

Property	Type	Description
`enum_information`	array	Denotes the available choices for enum fields.
`enum`	array	Denotes the available choices for enum fields and adheres to JSON Schema convention by only communicating the enum value (excluding properties like `description`). This compliant `enum` field may be useful for off-the-shelf JSON Schema validators, for example.

Example JSON Schema

1 {
2     "request_schema": {
3         "type": "object",
4         "properties": {
5             "model": {
6                 "type": "object",
7                 "properties": {
8                     "first_name": {
9                         "type": "string",
10                         "description": "The candidate's first name."
11                     },
12                     "last_name": {
13                         "type": "string",
14                         "description": "The candidate's last name."
15                     },
16                     "email_addresses": {
17                         "type": "array",
18                         "description": "Array of email_addresses objects on ats.Candidate",
19                         "items": {
20                             "type": "object",
21                             "properties": {
22                                 "value": {
23                                     "type": "string",
24                                 },
25                                 "email_address_type": {
26                                     "type": "string",
27                                 }
28                             },
29                             "required": ["value"], 
30                         }
31                     },
32                     "integration_params": {
33                         "type": "object",
34                         "properties": {
35                             "stage": {
36                                 "type": "string",
37                                 "enum": ["ARCHIVED", "ACTIVE"],
38                                 "enum_information": [
39                                     {
40                                         "value": "ARCHIVED",
41                                         "description": "Archived"
42                                     },
43                                     {
44                                         "value": "ACTIVE",
45                                         "description": "Active"
46                                     }
47                                 ]
48                             }
49                         },
50                         "required": ["stage"]
51                     }
52                 },
53                 "required": ["first_name", "last_name", "email_addresses"]
54             }
55         },
56         "required": ["model"]
57     }
58 }

Overview

Merge uses JSON Schema conventions in schemas returned from Merge (e.g., the request_schema returned from a /meta endpoint) for scalable schemas and programmatic convenience.

In these schemas:

Shared Properties specify type definitions with fields like “type” and “description”
Object, Array and Enum Fields will have additional schema properties as described further below

For programmatic validation of these schema properties, we encourage you to refer to the JSON Schema specification.

Shared Properties

All fields in JSON Schemas returned from Merge have basic properties like “type” and “description” that specify field types.

Property	Type	Description
`type`	string	Denotes the type of data stored in this field.
`description`	string	If available, will explain what data is expected.

Object Fields

In addition to shared properties, object fields in JSON Schemas returned from Merge will have these additional properties:

Property	Type	Description
`properties`	object	Denotes the object’s key-value pairs where the key is the field name and the value is the sub-schema of the field.
`required`	array	Denotes which object fields are required or optional when making a POST request.

Array Fields

In addition to shared properties, array fields in JSON Schemas returned from Merge will have these additional properties:

Property	Type	Description
`items`	object	`items` is an object describing the `type` and `properties` of the items of the array.

Enum Fields

In addition to shared properties, enum fields that have a limited array of string choices will have these additional properties:

Property	Type	Description
`enum_information`	array	Denotes the available choices for enum fields.
`enum`	array	Denotes the available choices for enum fields and adheres to JSON Schema convention by only communicating the enum value (excluding properties like `description`). This compliant `enum` field may be useful for off-the-shelf JSON Schema validators, for example.

Example JSON Schema

1 {
2     "request_schema": {
3         "type": "object",
4         "properties": {
5             "model": {
6                 "type": "object",
7                 "properties": {
8                     "first_name": {
9                         "type": "string",
10                         "description": "The candidate's first name."
11                     },
12                     "last_name": {
13                         "type": "string",
14                         "description": "The candidate's last name."
15                     },
16                     "email_addresses": {
17                         "type": "array",
18                         "description": "Array of email_addresses objects on ats.Candidate",
19                         "items": {
20                             "type": "object",
21                             "properties": {
22                                 "value": {
23                                     "type": "string",
24                                 },
25                                 "email_address_type": {
26                                     "type": "string",
27                                 }
28                             },
29                             "required": ["value"], 
30                         }
31                     },
32                     "integration_params": {
33                         "type": "object",
34                         "properties": {
35                             "stage": {
36                                 "type": "string",
37                                 "enum": ["ARCHIVED", "ACTIVE"],
38                                 "enum_information": [
39                                     {
40                                         "value": "ARCHIVED",
41                                         "description": "Archived"
42                                     },
43                                     {
44                                         "value": "ACTIVE",
45                                         "description": "Active"
46                                     }
47                                 ]
48                             }
49                         },
50                         "required": ["stage"]
51                     }
52                 },
53                 "required": ["first_name", "last_name", "email_addresses"]
54             }
55         },
56         "required": ["model"]
57     }
58 }

1	{
2	"request_schema": {
3	"type": "object",
4	"properties": {
5	"model": {
6	"type": "object",
7	"properties": {
8	"first_name": {
9	"type": "string",
10	"description": "The candidate's first name."
11	},
12	"last_name": {
13	"type": "string",
14	"description": "The candidate's last name."
15	},
16	"email_addresses": {
17	"type": "array",
18	"description": "Array of email_addresses objects on ats.Candidate",
19	"items": {
20	"type": "object",
21	"properties": {
22	"value": {
23	"type": "string",
24	},
25	"email_address_type": {
26	"type": "string",
27	}
28	},
29	"required": ["value"],
30	}
31	},
32	"integration_params": {
33	"type": "object",
34	"properties": {
35	"stage": {
36	"type": "string",
37	"enum": ["ARCHIVED", "ACTIVE"],
38	"enum_information": [
39	{
40	"value": "ARCHIVED",
41	"description": "Archived"
42	},
43	{
44	"value": "ACTIVE",
45	"description": "Active"
46	}
47	]
48	}
49	},
50	"required": ["stage"]
51	}
52	},
53	"required": ["first_name", "last_name", "email_addresses"]
54	}
55	},
56	"required": ["model"]
57	}
58	}