Creating relationships between data entities using API

Learn how to create relationships between data entities in Master Data v2.

This document will teach you how to establish relationships between data entities in Master Data v2. Creating these relationships is vital for organizing and structuring data efficiently within your system.

Before you begin

Before delving into the process of creating relationships, it's essential to grasp the structure of JSON Schema. If you're not familiar with JSON Schema, we recommend referring to the external documentation, Understanding JSON Schema.

To learn more about schemas in Master Data v2, see Schema lifecycle.

Establishing relationships

Use the Save schema by name ednpoint to configure a field to link to another data entity using either the ID or a field with an associated index created using the Create index endpoint.

Below are examples of both methods:

Link through ID


_10{
_10    "properties": {
_10        "clientEmail": { "type": "string" },
_10        "address": {
_10            "type": "string",
_10            "link": "https://vtexaccount.vtexcommercestable.com.br/api/dataentities/address/schemas/address-schema-v1"
_10        }
_10    }
_10}

Link through a field with an index


_10{
_10    "properties": {
_10        "clientEmail": { "type": "string" },
_10        "addressName": {
_10            "type": "string",
_10            "link": "https://vtexaccount.vtexcommercestable.com.br/api/dataentities/address/schemas/address-schema-v1",
_10            "linked_field": "addressName"
_10        }
_10    }
_10}

Notice that the link property associates a JSON Schema of the data entity with which you want to create a relationship.

Response handling

Creating a relationship in this manner will generate a response containing a new field with the JSON of the related document.

The fields in the returned object will match those specified in the v-default-fields. However, if the document does not exist with the specified key, the property will be populated with null.

Example of a Get document request without schema

GET /api/dataentities/client/documents/{id}?_fields={fields}


_10{
_10    "clientEmail": "vtext@mail.com",
_10    "address": "1"
_10}

Example of a Get document request using a schema with a link

In this request, you must use the _schema and the _fields query parameters for the linked fields to return correctly.

GET /api/dataentities/client/documents/{id}?_schema={schema}&_fields={fields}


_10{
_10    "clientEmail": "vtext@mail.com",
_10    "address": "1"
_10    "address_linked": {
_10        "id": "1"
_10        "city": "Rio de Janeiro"
_10    }
_10}