Skip to main content

Custom Fields

A Custom Field represents a single field of data (for example a Product Rating). A Custom API is composed of one or more Custom Fields.

Here is a comparison of different types and validation available in Custom APIs vs Non-Core Flows.

FeatureNon-Core FlowsCommerce Extensions
Data Type: String✅✅
Data Type: Integer✅✅
Data Type: Float✅✅
Data Type: Boolean✅✅
Data Type: Date & Time✅✅ Replaced by Regex Validation (See Below)
Data Type: One To Many✅Planned
Validation: Regular Expression⛔️✅
Validation: Slug/Email✅✅ Replaced by Regex Validation (See Below)
Validation: Min/Max Value✅✅
Validation: Enum(String)✅✅ Replaced by Regex validation (See Below)
Validation: Enum(Float/Integer)✅⛔️
Validation: Allow null values⛔✅
Validation: Unique(String)⛔✅
Validation: Unique Case Insensitivity(String)⛔✅
Validation: Immutable⛔✅

Validation​

When creating or updating a Custom Field, validation can be used to limit the values that may be stored in the corresponding Custom API Entry.

note

All validation changes, such as those to allow_null_values and any type specific rules, apply to new entries only. Existing Custom API Entry records are unaffected until updated.

Integer Validation​

  • min_value: Specifies the minimum whole number that can be stored. If set, it must be less than max_value.
  • max_value: Specifies the maximum whole number that can be stored. If set, it must be greater than min_value.

sample integer validation object:

{
  "validation": {
    "integer": {
      "min_value": 0,
      "max_value": 32
    }
  }
}

Even if no validation is set, field_type integer only supports values between -2^53+1 and 2^53+1. This is because the JSON format doesn't guarantee that values outside this range are portable (Source).

Float Validation​

  • min_value: Specifies the minimum number that can be stored. If set, it must be less than max_value.
  • max_value: Specifies the maximum number that can be stored. If set, it must be greater than min_value.

sample float validation object:

{
  "validation": {
    "float": {
      "min_value": 0.01,
      "max_value": 32.01
    }
  }
}

The float field_type cannot accurately represent some numbers and so using very small or large numbers might lose precision. We recommend that API clients use either the integer field_type if applicable , or the string data type if perfect precision or recall is required.

String Validation​

  • min_length: Specifies the minimum number of characters that can be stored. If set, it must be greater than 0 and less than max_length.
  • max_length: Specifies the maximum number of characters that can be stored. If set, it must be greater than 0 and min_length.
  • regex: An RE2 regular expression used to restrict the specific characters that can be stored. It must be less than 1024 characters.
  • unique: Specifies whether the field must have unique constraint or not. It must be yes or no.
  • unique_case_insensitivity: Applies when unique is set to yes. It controls whether values with different cases (for example, ABC and abc) should conflict. It must be true or false. sample string validation object:
{
  "validation": {
    "string": {
      "min_length": 0,
      "max_length": 64,
      "regex": "^.+\\.(jpg|jpeg|png|gif|pdf)$",
      "unique": "yes"
      "unique_case_insensitivity": true
    }
  }
}

Even if no validation is set, field_type string only supports values that are up to 65535 characters long.

Date & Time Values With Regular Expressions​

While Commerce Extensions does not have a native date or time type, you can none-the-less use these values in Commerce Extensions, by using the string field type and regex validation. To ensure that ordering is handled properly you should follow the guidance in RFC 3339 - Section 5.1 Ordering, namely store the fields in order of least to most precise, and in the same timezone, this will ensure that comparison operators (e.g., gt) and sorting, work as expected, for example the following regex will force all values to be in seconds in UTC: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

One thing to keep in mind is that some libraries, especially when dealing with sub-seconds might only display them if they are non-zero, and you will want to ensure that they are fully padded to the same length.

Enum Values with Regular Expressions​

You can ensure that only some values are allowed using the regular expression ^(alpha|bravo|charlie)$.

Slug Values with Regular Expressions​

Slugs can be replaced with the regular expression ^[a-z][a-z0-9-]*$, this will ensure that the field starts with a lower case letter, and then has lower case letters, numbers or hyphens. You can tweak this regular expression as needed to suit your needs.

Email Validation with Regular Expressions​

E-mails can be tricky to validate properly, especially because many services accept e-mails that are not valid, and reject e-mail addresses that are technically valid. Additionally, your own capabilities and purposes might inform your decision (e.g., if you support i18n addresses or don't then the set of allowed e-mails changes).

Null Values​

All Custom Fields can be configured to restrict the storage of null values for that field on a Custom API Entry. By default, this is true.

sample validation object :

{
  "validation": {
    "boolean": {
      "allow_null_values": false,
      "immutable": false
    }
  }
}

Immutable​

When creating a Custom Field, it can be configured to be immutable. When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests. By default, this is false.

sample validation object :

{
  "validation": {
    "boolean": {
      "immutable": false
    }
  }
}

Presentation​

When creating or updating a Custom Field, presentation can be used to influence the layout and order of fields within Commerce Manager. It does not affect the order of keys within JSON, nor influence any behaviour outside of Commerce Manager.

Reserved Slugs​

The following values cannot be used as a slug in a Custom Field.

  • slug
  • type
  • id
  • meta
  • created_at
  • updated_at
  • links
  • relationships
  • attributes
  • attribute
  • dimension
  • dimensions
  • weight
  • weights