JSON Configuration Files Schema

Creating a custom JSON configuration file requires using a custom module and building a new configuration file using JSON Schema V4. Follow this schema when introducing new properties associated with a custom module.

Important:

Configuration property keys must only contain alphanumeric characters and periods. The developer tools will not deploy configuration customizations that include special characters or spaces. Keys must also be unique across all configuration files.

Note:

This schema is compliant with Schema V4. JSON schemas, ensuring that all configuration files use a consistent structure and define required objects. For more information, see json-schema.org.

General Structure

Each configuration file contains a root object that defines the configuration information for a module. At the root level, all configuration files must define the type, group, and properties objects. This schema allows for the addition of the subtab object as an option.

The following example depicts the general structure and order of a JSON configuration file.

          //...
{
    "type": "object",
    "group": {
        //...
    },
    "properties": {
        //...
    }
}
//...

Type

The type object specifies the type of object defined by the configuration file. The value of this object must always be set to object and it must be specified in the first line of the configuration file. This is required to be compliant with the JSON schema specification.

          //...
{
      "type": "object",
      //...
}
//...

Group

The SCA Configuration record uses this metadata to determine the tab in which to display configuration properties. The group object defines the following:

id – defines an internal identifier for the tab in the SuiteCommerce Configuration record. The id must only contain alphanumeric characters and periods (no other special characters or spaces), and must be unique across all configuration files.
title – defines the label of the tab displayed in the SuiteCommerce Configuration record.
description – provides a description of the group object.

Additional metadata in the group object may also control which groups appear in the SuiteCommerce Configuration record user interface. See Conditional Display of Groups and Subtabs.

The following example, taken from the checkoutApplications.json file, initiates the Checkout tab using the group id (checkoutApp). Any subtabs or properties appearing in this tab of the UI must declare this group id.

          //...
"group": {
    "id": "checkoutApp",
    "title": "Checkout",
    "description": "Checkout Application configuration"
},
//...

Subtab

The SCA Configuration record uses this metadata to determine the subtab in which to display any nested properties. The subtab object, if used, defines the following:

id – defines an internal identifier for the subtab in the SuiteCommerce Configuration record. The id must only contain alphanumeric characters and periods (no other special characters or spaces), and must be unique across all configuration files.
title – defines the label of the subtab displayed in the SuiteCommerce Configuration record.
description – provides a description of the subtab object.
group – defines the group object to which the subtab is assigned. This is the tab where the subtab appears in the UI.

Additional metadata in the Subtab object may also control which subtabs appear in the SuiteCommerce Configuration record user interface. See Conditional Display of Groups and Subtabs.

The following example, taken from the checkoutApplications.json file, initiates the Forms subtab using the subtab id (checkoutForms) and group id (checkoutApp). This locates the Forms subtab within the Checkout tab, as shown in the following image.

          //...
{
      "subtab": {
            "id": "checkoutForms",
            "title": "Forms",
            "description": "Checkout configuration related to web forms.",
            "group": "checkoutApp"
      },
//...

Shows the Forms subtab in the Checkout tab

Conditional Display of Groups and Subtabs

To control the display of specific groups (tabs) and subtabs based on the website scope and features enabled in your account, add conditional display keys to module and extension JSON configuration files. These conditional display keys apply to group and subtab objects. The conditional display keys do not apply to individual properties. There are two important considerations when using conditional display keys:

You may use one or more condition keys to control the display of a group and subtab.
All used condition keys must evaluate to true to conditionally display the group or subtab.

There are two valid website scope keys and three valid feature keys.

Valid Website Scope Keys (case-sensitive)

showIfNoneWebsiteScope

Use this key to conditionally display a group or subtab based on a specific website scope (website type) not implemented in your account.
showIfAnyWebsiteScope

Use this key to conditionally display a group or subtab based on a specific website scope (website type) implemented in your account.

Valid Website Scope Values (case-sensitive)

Website Scope

Value

SuiteCommerce

SUITE_COMMERCE

SuiteCommerce Advanced

SUITE_COMMERCE_ADVANCED

SuiteCommerce MyAccount

SUITE_COMMERCE_MY_ACCCOUNT

SuiteCommerce InStore

SUITE_COMMERCE_IN_STORE

Site Builder Full Web Store

FULL_WEB_STORE

Site Builder Information and Catalog with Pricing

INFO_CATALOG_PRICING

Site Builder Information Only

INFO_ONLY

Valid Feature Keys

showIfNoneFeatures

Use this key to conditionally display a group or subtab based on a specific feature not implemented in your account.
showIfAnyFeatures

Use this key to conditionally display a group or subtab based on one or more specific features implemented in your account.
showIfAllFeatures

Use this key to conditionally display a group or subtab based on a specific set of features all implemented in your account.

Valid Feature Values (case-sensitive)

Field IDs are used for feature key values. To find the valid values (Field IDs) for feature keys:

In NetSuite, go to Home > Set Preferences.
In the Defaults section, enable the Show Internal IDs option.
Click Save.
Go to Setup > Company > Enable Features.
Click on the field title of any of the available features to display the field level help. The Field ID is shown at the bottom right portion of the field help text.

Field ID Example:

Example:

The sample below shows how to edit the CheckoutApplication.json file to condition the display of the Checkout group (tab) and Forms subtab by adding conditional website scope and feature keys to the group and subtab objects. This file is located in the Configuration folder of your CheckoutAppplication module folder. In the example code below, the Checkout group (tab) and Forms subtab will only display if the following conditions are true:

You are not implementing SuiteCommerce In Store
You are implementing either SuiteCommerce Advanced or SuiteCommerce
You are not implementing the Web Duplicated Email Management feature
You are implementing the Multilanguage or Multicurrency feature
You are implementing Advanced Site Management and Commerce Search Analytics features on a SuiteCommerce Advanced site

            {
    "type": "object",
    "group": {
           "id": "checkoutApp",
               "title": "Checkout",
               "docRef": "bridgehead_4393268798",
               "description": "Checkout Application configuration"
               "showIfNoneWebsiteScope":["SUITE_COMMERCE_IN_STORE"],
               "showIfAnyWebsiteScope":["SUITE_COMMERCE_ADVANCED","SUITE_COMMERCE"],
               "showIfNoneFeatures":["webduplicateemailmanagement"],
               "showIfAnyFeatures":["multilanguage","multicurrency"].
               "showIfAllFeatures":["suitecommerce_advanced","advancedsitemanagement","commercesearchanalytics"]
    },
    "subtab": {
            "id": "checkoutForms",
            "title": "Forms",
            "docRef": "section_4700765645",
            "description": "Checkout configuration related to web forms.",
            "group": "checkoutApp",
               "showIfNoneWebsiteScope":["SUITE_COMMERCE_IN_STORE"],
               "showIfAnyWebsiteScope":["SUITE_COMMERCE_ADVANCED","SUITE_COMMERCE"],
               "showIfNoneFeatures":["webduplicateemailmanagement"],
               "showIfAnyFeatures":["multilanguage","multicurrency"],
               "showIfAllFeatures":["suitecommerce_advanced","advancedsitemanagement","commercesearchanalytics"]
         },
...

Resource

The resource object specifies data available as a resource within the configurationManifest.json file. You can later refer to this resource using the source of a properties object to determine the possible choices of a configurable property.

In the following example from categories.json, the resource object defines the commerce category fields to make available as a resource.

          //...
"resource": {
   "fields": {
      "commercecategory": [
         "internalid", "name", "description", "pagetitle", "pageheading", "pagebannerurl" //...
      ]
   }
}
//...

Properties

The properties object defines the configuration properties for a module. This object can define one or more properties as object literals. These object literals define the associated property’s members/attributes and their values, delimited by commas.

Each properties object can define values for the following:

Id
Group
Subtab
Type
Title
Description
Items
Enum
Multiselect
Default
Mandatory
Translate
Source
Hidden
Nstype

Id

The id is the key used in the properties object as the property object declaration. This forms the location of the property in the final configuration object structure. The id is required. The id must only contain alphanumeric characters and periods (no other special characters or spaces), and must be unique across all configuration files. In the following example, the property declaration, productReviews.maxFlagCount": {type: "string", ...}, results in the following configuration object:

          //...
{   
      productReviews: {
     maxFlagCount: 1   
      }
}
//...

Group

The group attribute specifies the id of the corresponding group object (tab) where the property appears in the UI. This attribute is required.

The following example from checkoutApp.json defines the group value of the checkoutApp.skipLogin property as checkoutApp. Consequently, this property appears on the Checkout tab in the UI:

          //...
, "properties": {
         "checkoutApp.skipLogin": {
               "group": "checkoutApp",
               "type": "boolean",
               "title": "Skip Checkout Login",
               "description": "Check this box to enable anonymous users to skip the login/register page...",
               "default": false
         },
//...

Subtab

The subtab attribute specifies the id of the corresponding subtab object (subtab) where the configurable property appears in the UI.

The following example from checkoutApp.json defines the subtab value of the autoPopulateNameAndEmail property as checkoutForms, defined earlier. Note that this property also declares the group associated with the Checkout tab. Consequently, this property appears on the Checkout tab and the Forms subtab in the UI:

          //...
      "autoPopulateNameAndEmail": {
            "group": "checkoutApp",
            "subtab": "checkoutForms",
            "type": "boolean",
            "title": "Auto populate name and email",
            "description": "Check this box to enable auto-population of a guest shopper's name...",
            "default": true
      },  
//...

Type

The type attribute specifies the data type of the configurable property. If specified, the user must enter a value of this type in the SuiteCommerce Configuration record. This must be a valid JSON-supported type: integer, string, boolean, array, or object. This attribute is required.

The following example from checkoutApp.json defines the checkoutApp.skipLogin property is defined as a boolean value:

          //... 
, "properties": {
         "checkoutApp.skipLogin": {
               "group": "checkoutApp",
               "type": "boolean",
               "title": "Skip Checkout Login",
               "description": "Check this box to enable anonymous users to skip the login/register page...",
               "default": false
         },
//...

Title

The title attribute defines the label that appears in the SuiteCommerce Configuration record. In the preceding example, the SuiteCommerce Configuration record displays the checkoutApp.skipLogin property as Skip Checkout Login. This attribute is required.

Description

The description attribute specifies a string that displays as help text when a user points to a label in the SuiteCommerce Configuration record.

Any property, subtab, or group can declare a description. The SuiteCommerce Configuration record displays the description on simple properties only.

Items

If a property’s type value is set to an array, items is required to define the different properties of the table in the SuiteCommerce Configuration record.

The following example from facets.json initializes Facets as “type” : “array”. This displays as an array of properties in the SuiteCommerce Configuration record. The items attribute defines metadata to further define each configurable property (column), as shown in the image below.

          //...
"facets": {
         "group": "catalog",
         "type": "array",
         "title": "Facets",
         "docRef": "bridgehead_4393383668",
         "description": "Facets editor declarations",
         "items": {
                  "type": "object",
                  "properties": {
                        "id": {
                  "type": "string",
                  "title": "item field id",
                  "description": "NetSuite item field id, something like 'custitem31'",
                  "mandatory": true
                },
             "name": {
                   "type": "string",
                 "title": "Name",
                 "translate": true,
                 "description": "Label for this facet in the UI",
                 "mandatory": true
             },
             "url": {
                   "type": "string",
                 "title": "Url",
                 "description": "Url fragment for identifying the facet in the url.",
             },
//...

Shows the resulting properties columns for each item in the Facets subtab

Enum

The enum attribute specifies the set of available values for a configurable property. By default, when enum specifies multiple values, the user can only select one of the possible values. This generates a list of possible selections in the UI.

Note:

Adding the enum attribute to a property renders that property as a select or multi-select field in the SuiteCommerce Configuration record UI. To render a property as a multi-select field, set the multiselect attribute to true.

The following example from facets.json specifies five possible values for the facetsSeoLimits.options property (order, page, show, display, or keywords):

          //...
"facetsSeoLimits.options": {
    "type": "string",
    "group": "catalog",
    "subtab": "facetsSeoLimits", 
    "title": "Options",
    "description": "Description of this property",
    "enum": ["order", "page", "show", "display", "keywords"],
    "default": ["page", "keywords"],
    "multiselect": true
},
//...

Multiselect

The multiselect attribute specifies that a configurable property can contain multiple values in the UI. If set to true, users can select multiple values as defined in enum. This generates a multi-select list in the UI.

In the previous example, the facetsSeoLimits.options property is set to accept multiple values with the following code:

          "multiselect": true

Consequently, users can choose multiple options from the SuiteCommerce Configuration record UI. The property can also accept multiple default values as defined in the default attribute.

Default

The default attribute specifies default values based on the property type, defined earlier. These values automatically populate fields in the SuiteCommerce Configuration record UI. Defaults load in the application at runtime. These defaults are only superseded by changes saved in the SuiteCommerce Configuration record. If no user saves a record, the application uses the defaults specified here.

In the previous example, the default values for the facetsSeoLimits.options property are page and keywords.

Mandatory

The mandatory attribute specifies that a property is required. In the following example from facets.json, the name property is set to true. Consequently, the attribute is required.

          //...
"name": {
    "type": "string",
    "title": "Name",
    "translate": true,
    "description": "Label for this facet in the UI",
    "mandatory": true
},
//...

Translate

The translate attribute specifies that the title and description attribute values must be translated. If this is set to true, its default values are translated. In the preceding example, the name property’s title and description fields are set to be translated.

Source

The source attribute declares the data source to be used as possible choices when configuring the property in the UI. This can include a variable that refers to the resource object declared within the JSON file (or within another JSON file that makes up the configurationManifest.json).

Note:

Adding the source attribute to a property renders that property as a select or multi-select field in the SuiteCommerce Configuration record. To render a property as a multi-select field, set the multiselect attribute’s value to true.

The following example from categories.json uses the source attribute to refer to a local resource object (fields.commercecategory). In this example, $resource references the fields.commercecategory array:

          //...
"categories.sideMenu.sortBy": {
   "group": "integrations",
   "subtab": "categories",
   "type": "string",
   "title": "Side menu > sort by",
   "description": "Enter the Category record field to act as the primary sort field in the Categories sidebar.",
   "source": "$resource.fields.commercecategory",
   "default": "sequencenumber"
//...

The source attribute can also refer to data within some custom records in NetSuite via SuiteScript. In this case, source references elements of a specific record type. The variable used must match the Internal ID of a applicable custom record types.

The following fictitious example uses the source attribute to provide a list of all support issues within NetSuite (record type: Issue):

          //...
"issue": {
   "type": "string",
   "title": "Support Issues",
   "source":  "issue"
}
//...

Hidden

The hidden attribute specifies that a property is hidden and not shown in the user interface. If set to true, the property's default values are still present in configurationManifest.json, but the user will not be able to see or edit the property using the SuiteCommerce Configuration record.

Nstype

The nstype attribute specifies a concrete NetSuite widget for editing a type parameter. If a text field is too long for normal text entry, the user can declare "nsType": "textarea" and the user interface will show a text area instead a normal text entry.

The following example from checkoutApp.json declares the nstype:

          //...
"checkoutApp.invoiceTermsAndConditions": {
    "group": "checkoutApp",
    "type": "string",
    "nsType": "textarea",
    "title": "Invoice Terms and Conditions",
    "description": "Invoice payment method terms and conditions text",
    "default": "<h4>Invoice Terms and Conditions</h4.><p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<p>"
},
//...

General Notices