JSON Configuration Files Schema

This topic applies to

Applies to

Aconcagua | Elbrus | Kilimanjaro | SuiteCommerce Web Stores | Vinson

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.

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 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.

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 (no special characters), 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.

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"
      },
//...

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. 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. As a result, 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. As a result, 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:

//... 
, "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.",
             },
//...
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

As a result, 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. As a result, 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.

Note

See the help topic addField(name, type, label, sourceOrRadio, tab) for more details on the applicable record types. See SuiteScript 1.0 API for more information about using SuiteScript objects.


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>"
},
//...