Specifications

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.

PropertyTypeDescription
typestringDenotes the type of data stored in this field.
descriptionstringIf 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:

PropertyTypeDescription
propertiesobjectDenotes the object’s key-value pairs where the key is the field name and the value is the sub-schema of the field.
requiredarrayDenotes 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:

PropertyTypeDescription
itemsobjectitems 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:

PropertyTypeDescription
enum_informationarrayDenotes the available choices for enum fields.
enumarrayDenotes 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

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}