Schema relations

Relations are defined between schemas, but applied in practice to records of these schemas.

For example, you can create a list of people and a list of projects where these people are involved.

To do this, you need to:

Create two schemas and define relations between them OR update existing schemas with relations.
Connect employee records with project records.

A practical example is provided further in this article.

Relation types

In the explanations below, the following terms are used:

Origin schema: the schema that is the source of the relation. In our example, this is the project schema.
Right Hand Schema (RHS): the schema that is the target of the relation. In our example, this is the employee schema.

The available relation types are:

one_to_many: origin schema record can store multiple references to RHS records; RHS record can store one reference to origin schema record.
many_to_many: origin schema record can store multiple references to RHS records; RHS records can store multiple references to origin schema records.
many_to_one: origin schema record can store one reference to RHS record; RHS record can store multiple references to origin schema records.
one_to_one: origin schema record can store one reference to RHS record; RHS record can store one reference to an origin schema record.

Important: A schema can include multiple relation definitions.
Relations are not mutually exclusive - at the same time, you can have a relation that allows each person to be assigned to only one project and another, where a person can belong to many projects.
An example is creating one relation to assign project leaders (a person can only lead one project at a time) and another relation to assign all project stakeholders (a project leader can be involved in the workflows of many other projects).

Relation example

Tip: This example is also described in the user documentation, from the GUI perspective.

The example shows how to create a project-employee relation, in which an employee can only be associated with one project and a project can have many employees assigned.

The example assumes that you create new schemas, but you can add relations to existing schemas in the same way by updating the schemas.

Tip: For easier reading, the code samples in the example are simplified by omitting some fields and their values.

The schemas used in this example are different (simpler) than the example schema in Creating schemas and Creating records.

Project schema

This schema only stores one value: the name of the project.

It does not have any relation defined, because the employee schema does not exist yet in this example, so a relation cannot be created.

{
    "schemaName": "Simple project",
    "fields": {
        "projectName": {
            "type": "TEXT",
            "design": {
                "label": "Project name",
                ...
            },
            "layout": {
                ...
            },
            "validation": {
                ...
            }
        }
    },
    "layout": [
        {   
            "type": "SINGLE",
            "fieldName": "projectName"
        }
    ]
}

Employee schema

The schema has two fields:

the name of the employee
the definition of a relation (highlighted lines)

{
    "schemaName": "Employee",
    "fields": {
        "fullName": {
            "type": "TEXT",
            "design": {
                "label": "Employee name",
                ...
            },
            "layout": {
                ...
            },
            "validation": {
                ...
            }
        },
        "project_with_many_employees": {
            "type": "SELECT",
            "data": {
                "source": {
                    "type": "RELATION",
                    "data": {
                        "rhsSchemaId": "2ea3cb78-a7a4-4448-8ca8-714e3da46c79", // employee schema
                        "relationType": "one_to_many",
                        "displayField": "projectName" // field used to represent the connected record
                                                      // in the list of records in the GUI
                    }
                }
            },
            "design": {
                "label": "Project with many employees",
                ...
            },
            "layout": {
                ...
            },
            "validation": {
                ...
            }
        }
    },
    "layout": [
        {
            "type": "SINGLE",
            "fieldName": "fullName"
        },
        {
            "type": "SINGLE",
            "fieldName": "project_with_many_employees"
        }
    ]
}

After creating this relation in the employee schema, the project schema is updated automatically with the relation. The displayField in the project schema is not defined. You can edit the project schema to define the displayField and label parameters of the automatically created relation field.

Connecting records

Important:

This example of connecting records assumes creating new records and connecting them.

If you created records before a relation was created in the schema definition, those existing records are automatically updated with relation data, without any references to other records. To create references between existing records, update those records with the same data as when creating a connection during record creation.

Create a project record.
The relation must be listed, but the list of connected records is empty, because employee records do not exist yet in this example.

curl --location --request \
POST 'https://{SYNERISE_API_BASE_PATH}/boxes-v2/records/bcb027b1-4b49-44fb-9f96-7a3c710af7cf' \
--header 'api-version: 4.2' \
--header 'authorization: Bearer eyJ...cp2H8' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fields": {
        "projectName": {
            "value": "The Founding of Rome"
        },
        "project_with_many_employees": {}
    }
}'

The response contains the data of the created record.

From the response, note down the recordId of the project record.
You can also retrieve a list of records from a schema.

Create an employee record with a relation to the project record.

curl --location --request \
POST 'https://{SYNERISE_API_BASE_PATH}/boxes-v2/records/2ea3cb78-a7a4-4448-8ca8-714e3da46c79' \
--header 'api-version: 4.2' \
--header 'authorization: Bearer eyJ...oidA' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fields": {
        "fullName": {
            "value": "Romulus"
        },
        "project_with_many_employees": {
            "type": "one", // an employee can be assigned to one project
            "recordId": "2492bac8-92c1-4bce-919e-7979cd1d1afe"
        }
    }
}'

The response contains the data of the created record.

Result:
The relation is added to the employee record.

                     { ... "fields": { "projectName": { "value": "The Founding of Rome" }, "project_with_many_employees" { "type": "many", // A project can have many employees assigned class="cl">            "recordIds": [ "e0f50659-459d-4bd5-84b5-4ad21426d97c" // ID of the employee record class="cl">            ] } }, ... "recordId": "2492bac8-92c1-4bce-919e-7979cd1d1afe", "relations": { "project_with_many_employees": { "type": "many", "recordIds": [ "e0f50659-459d-4bd5-84b5-4ad21426d97c" ], } }, "schemaId": "bcb027b1-4b49-44fb-9f96-7a3c710af7cf" class="p">}

Schemas with multiple relations

To define multiple relations to other schemas, add them as new fields:

    "fields": {
        "project_with_many_employees": {
            "type": "SELECT",
            "data": {
                "source": {
                    "type": "RELATION",
                    "data": {
                        "rhsSchemaId": "2ea3cb78-a7a4-4448-8ca8-714e3da46c79",
                        "relationType": "one_to_many"
                    }
                }
            },
            "design": {
                "label": "Project with many employees",
                ...
            },
            "layout": {
                ...
            },
            "validation": {
                ...
            }
        },
        "one_project_per_manager": {
            "type": "SELECT",
            "data": {
                "source": {
                    "type": "RELATION",
                    "data": {
                        "rhsSchemaId": "848024c6-374a-4bf4-94b0-887cb4ad7e1f", 
                        "relationType": "one_to_one"
                    }
                }
            },
            "design": {
                "label": "Project with one manager",
                ...
            },
            "layout": {
                ...
            },
            "validation": {
                ...
            }
        }
    },

Updating references between records

To update the connections between records, change the ID or IDs of connected records by updating the record. When you add/remove a reference in a record, the referenced records are updated automatically.

Records with no references

If a record is created from a schema that has relations defined, the field associated with that relation must always be sent. If no records need to be referenced, the object is empty.

    "fields": {
        "projectName": {
            "value": "The Founding of Rome"
        },
        "project_with_many_employees": {}
    }