Documentation
Feedback
Guides
API Reference

Guides
Master DataHow it works
VTable

VTable has been deprecated, which means it will not be updated, and support and maintenance are no longer provided.

VTable is a dynamic user interface designed to handle data from Master Data v2 directly from VTEX Admin. It allows you to create custom applications for managing and visualizing data from documents efficiently, using JSON schemas.

To render an app in VTable you must follow these steps:

VTable interface displays up to 14 documents in each app. It is not possible to increase this limit, since VTable is deprecated.

Below you can also learn more about all necessary JSON schema configurations.

Step by step

Step 1 - Creating a JSON schema

First, create a data entity and a JSON schema associated with it to store data in a specific format.

You can create it with the Save schema by name endpoint. Use your JSON schema as a request body, as exemplified below.

Check the JSON schema configurations section to learn how to configure each field for your specific needs.

Example JSON schema (request body)

_35
[
_35
{
_35
"name": "v1",
_35
"schema": {
_35
"properties": {
_35
"email": {
_35
"type": "string"
_35
},
_35
"firstName": {
_35
"type": "string"
_35
},
_35
"lastName": {
_35
"type": "string"
_35
}
_35
},
_35
"v-indexed": [
_35
"email",
_35
"firstName",
_35
"lastName"
_35
],
_35
"v-default-fields": [
_35
"id",
_35
"email",
_35
"firstName",
_35
"lastName"
_35
],
_35
"v-cache": false,
_35
"required": [
_35
"email",
_35
"firstName",
_35
"lastName"
_35
]
_35
}
_35
}
_35
]

Step 2 - Building the app schema

To create a VTable app, you must define a schema that specifies the data VTable will use to render a table.

The app schema you create must follow the structure indicated by the VTable app objects schema below.

For now, start with the Example app schema below and edit it according to your data.

You will validate your app schema's structure in the following step.

VTable app objects schema

_134
{
_134
"properties": {
_134
"name": {
_134
"type": "string",
_134
"minLength": 1,
_134
"maxLenght": 50
_134
},
_134
"title": {
_134
"type": "string",
_134
"minLength": 1,
_134
"maxLenght": 50
_134
},
_134
"tables": {
_134
"type": "array",
_134
"minItems": 1,
_134
"items": {
_134
"type": "object",
_134
"properties": {
_134
"id": {
_134
"type": "string",
_134
"minLength": 1
_134
},
_134
"title": {
_134
"type": "string",
_134
"minLength": 1
_134
},
_134
"entity": {
_134
"type": "string",
_134
"minLength": 1
_134
},
_134
"model": {
_134
"type": "string",
_134
"minLength": 1
_134
},
_134
"list": {
_134
"type": "array",
_134
"minItems": 1,
_134
"uniqueItems": true,
_134
"items": {
_134
"type": "string",
_134
"minLength": 1
_134
}
_134
},
_134
"editor": {
_134
"type": "object",
_134
"properties": {
_134
"settings": {
_134
"type": "object",
_134
"properties": {
_134
"sections": {
_134
"type": "array",
_134
"minItems": 1,
_134
"items": {
_134
"type": "object",
_134
"properties": {
_134
"name": {
_134
"type": "string",
_134
"minLength": 1
_134
},
_134
"fields": {
_134
"type": "array",
_134
"minItems": 1,
_134
"uniqueItems": true,
_134
"items": {
_134
"type": "string",
_134
"minLength": 1
_134
}
_134
}
_134
},
_134
"required": [
_134
"name",
_134
"fields"
_134
]
_134
}
_134
}
_134
},
_134
"required": [
_134
"sections"
_134
]
_134
}
_134
},
_134
"required": [
_134
"settings"
_134
]
_134
},
_134
"fields": {
_134
"type": "object",
_134
"properties": {
_134
"id": {
_134
"type": "object",
_134
"properties": {
_134
"width": {
_134
"type": "integer"
_134
}
_134
},
_134
"required": [
_134
"width"
_134
]
_134
}
_134
},
_134
"required": [
_134
"id"
_134
],
_134
"additionalProperties": {
_134
"type": "object",
_134
"properties": {
_134
"width": {
_134
"type": "integer"
_134
}
_134
},
_134
"required": [
_134
"width"
_134
]
_134
}
_134
}
_134
},
_134
"required": [
_134
"fields",
_134
"entity",
_134
"model",
_134
"id",
_134
"title",
_134
"list",
_134
"editor"
_134
]
_134
}
_134
}
_134
},
_134
"required": [
_134
"name",
_134
"title",
_134
"tables"
_134
]
_134
}

Example app schema

_42
{
_42
"name":"users",
_42
"title":"Users Admin",
_42
"tables":[
_42
{
_42
"id":"main",
_42
"title":"Users",
_42
"entity":"users",
_42
"model":"user-v1",
_42
"fields":{
_42
"id":{
_42
"width":200
_42
},
_42
"email":{
_42
"width":200
_42
},
_42
"firstName":{
_42
"width":300
_42
}
_42
},
_42
"list":[
_42
"email",
_42
"firstName",
_42
"lastName"
_42
],
_42
"editor":{
_42
"settings":{
_42
"sections":[
_42
{
_42
"name":"Personal Data",
_42
"fields":[
_42
"firstName",
_42
"email",
_42
"lastName"
_42
]
_42
}
_42
]
_42
}
_42
}
_42
}
_42
]
_42
}

You can use this example app schema as a foundation to create your own app. Check the meaning of fields in the example app schema:

FieldTypeDescription
namestringName of the schema in Master Data v2.
titlestringApp title.
tablesarray of objectsList of objects containing information about the tables.
tables[i].idstringTable ID.
tables[i].titlestringTable title.
tables[i].entitystringTable entity that corresponds to the data entity in Master Data, which must exist before creating the app.
tables[i].modelstringModel that relates to the schema associated with the Master Data data entity.
tables[i].fieldsobjectList of fields to be displayed. Each field specifies the width it occupies in the table.
tables[i].fields.idobjectField name.
tables[i].fields.id.widthintegerWidth of the id field.
tables[i].fields.emailobjectField name.
tables[i].fields.email.widthintegerWidth of the email field.
tables[i].fields.firstNameobjectField name.
tables[i].fields.firstName.widthintegerWidth of the firstName field.
tables[i].listarray of stringsDefines the fields to be rendered in the table.
tables[i].editorobjectObject responsible for configuring the form's rendering.
tables[i].editor.settingsobjectForm settings.
tables[i].editor.settings.sectionsarray of objectsList of form sections and their respective settings.
tables[i].editor.settings.sections[j].namestringSetting name.
tables[i].editor.settings.sections[j].fieldsarray of stringsList of fields shown in the form.

Read the JSON schema configurations section to learn how to configure each field for your specific needs.

Step 3 - Validating the app schema

To validate your app schema, use a tool such as JSON Schema Validator, which allows you to paste the code from VTable app objects schema and the code from your app schema created in step 2 to check if the structure of your app schema is valid.

Step 4 - Saving the app schema to Master Data

To save the app schema to Master Data, send a PUT request to the Create document with custom ID endpoint, adding your app schema as the request body and filling the URL with the information below:

PUT https://{accountName}.{environment}.com.br/api/dataentities/vtable/documents/{appName}?_schema=app

Your app schema will be saved as a document in the VTable data entity.

After that, you will be able to access the app data in VTable at https://{accountName}.myvtex.com/admin/vtable/, replacing {accountName} with your VTEX account name.

JSON schema configurations

VTable parses the JSON Schema configuration and each field to a corresponding UI component. These are some examples of possible configurations:

Checkbox

Set the value of the type field as boolean to render a checkbox.


_10
"approved": {
_10
"type": "boolean",
_10
"title": "Approved"
_10
}

Dropdown

Add the enum property to render dropdown options.


_10
"gender": {
_10
"type": "string",
_10
"enum": [
_10
"Male",
_10
"Female"
_10
]
_10
}

DatePicker

Add the format property with the value date-time to render a date picker.


_10
"birthdate":{
_10
"type":"string",
_10
"format":"date-time"
_10
}

TextArea

Add the type string and the property multiline set to true in the app configuration to render a TextArea field.

JSON Schema configuration:


_10
"lastName":{
_10
"type":"string",
_10
"title":"LastName",
_10
"maxLenght":250
_10
}

App configuration:


_10
"lastName":{
_10
"width":300,
_10
"multiLine":true
_10
}

Link

The LinkControl represents the reference of one data entity to another data entity. To render the LinkControl set the properties link and linked_field where the value of link is the link to the referenced schema and the value of linked_field is the field that will be referenced.

The LinkControl lets you navigate between the related tables. For that, you need to set the properties relatedApp and relatedTable in the app configuration.

JSON Schema configuration:


_10
"user":{
_10
"type":"string",
_10
"link":"http://api.vtex.com/{accountName}/dataentities/users/schemas/user-v1",
_10
"linked_field":"email"
_10
}

App configuration:


_10
"user":{
_10
"width":300,
_10
"relatedApp":"users",
_10
"relatedTable":"main"
_10
}

TextBox

Add a string, number, or integer to render a TextBox. All properties of the JSON Schema that are used to validate the field (e.g., pattern, minLength, maxLength) will be used by VTable to validate the value of the field.

You can add a mask to the field in the app configuration to require a specific value format.

JSON Schema configuration:


_10
"phone":{
_10
"type":"string",
_10
"maxLength":100,
_10
"title":"Phone",
_10
"pattern":"[0-9]{10,11}"
_10
}

App configuration:


_10
"phone":{
_10
"width":200,
_10
"mask":"(99) 99999-9999"
_10
}

MultiOptions

Set the field type to array and define that each item must be a string to render a MultiOptions control. Each item must contain the enum property, which is an array with the possible strings for that field.


_14
"nationality":{
_14
"type":"array",
_14
"items":{
_14
"type":"string",
_14
"enum":[
_14
"Brasil",
_14
"Argentina",
_14
"Colombia",
_14
"Uruguai",
_14
"Chile",
_14
"Paraguai"
_14
]
_14
}
_14
},

ArrayControl

If the field type is array and the field schema does not match a special case, VTable will use ArrayControl.


_21
"list":{
_21
"type":"array",
_21
"title":"List",
_21
"items":{
_21
"type":"object",
_21
"properties":{
_21
"productId":{
_21
"type":"string",
_21
"title":"ProductId"
_21
},
_21
"quantity":{
_21
"type":"integer",
_21
"title":"Qty"
_21
},
_21
"name":{
_21
"type":"string",
_21
"title":"Name"
_21
}
_21
}
_21
}
_21
}

ObjectControl

Set the field type to object to render an ObjectControl field. The ObjectControl field is recursive, so it can hold another object as a property.


_36
"complex":{
_36
"type":"object",
_36
"title":"Complex",
_36
"properties":{
_36
"name":{
_36
"type":"string",
_36
"title":"Name"
_36
},
_36
"age":{
_36
"type":"number",
_36
"title":"Age",
_36
"minimum":0,
_36
"maximum":100
_36
},
_36
"birthdate":{
_36
"type":"string",
_36
"title":"BirthDate",
_36
"format":"date-time"
_36
},
_36
"innerObject":{
_36
"type":"object",
_36
"properties":{
_36
"innerName":{
_36
"type":"string",
_36
"title":"InnerName"
_36
},
_36
"innerAge":{
_36
"type":"number",
_36
"title":"Idade 3",
_36
"minimum":0,
_36
"maximum":100
_36
}
_36
}
_36
}
_36
}
_36
}

To learn more, check the Master Data v2 API documentation.

Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
On this page