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 to configure a field to link to another data entity using either the ID or a field to which there is some associated index.

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.

PATH: /api/dataentities/client/documents/{id}


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

Example of a Get document request using schema with link.

PATH: /api/dataentities/client/documents/{id}


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