Checkdigit
See Checkdigit for more information about this algorithm framework.
Creating a checkdigit algorithm via API
1. Retrieve the frameworkId for the Checkdigit Framework. This information can be retrieved using the following endpoint:
algorithm GET /algorithm/frameworksThe framework information should look similar to the following:
{
"frameworkId": 8,
"frameworkName": "Checkdigit",
"frameworkType": "STRING",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"plugin": {
"pluginId": 7,
"pluginName": "dlpx-core",
"pluginAuthor": "Delphix Engineering",
"pluginType": "EXTENDED_ALGORITHM" }
}2. Create a Checkdigit algorithm via the following endpoint:
algorithm POST /algorithmsThe schema for the algorithm is described in the following endpoint:
algorithm GET /algorithm/frameworks/id/{frameworkId}And looks similar to the following:
{
"frameworkId": 8,
"frameworkName": "Checkdigit",
"frameworkType": "STRING",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"plugin": {
"pluginId": 7,
"pluginName": "dlpx-core",
"pluginAuthor": "Delphix Engineering",
"pluginType": "EXTENDED_ALGORITHM"
},
"extensionSchema": {
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit",
"properties": {
"numericAlgorithm": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the digits of the input value prior to checkdigit(s) calculation.",
"properties": {
"name": {
"type": "string",
"required": true,
"description": "The algorithm instance name, starting with \":\" for instances provided by this plugin"
},
"algorithmMetadata": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference:AlgorithmReferenceMetadata",
"description": "Metadata values passed to the chained algorithm. Can be used to control how automatic type conversions are performed.",
"properties": {
"dateFormat": {
"type": "string",
"description": "The expected date format of a date value being masked."
},
"maxLength": {
"type": "integer",
"description": "The maximum size of the value being masked."
},
"stringMaxLengthEncoded": {
"type": "boolean",
"description": "Boolean value indicating whether the value maxLength represents the maximum Java String length in characters (false), or a byte length limit."
},
"stringCharsetName": {
"type": "string",
"description": "The name of the Charset used to encode string values."
}
}
}
}
},
"fallbackAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the input data if it does not appear in the expected format."
},
"preserveRegex": {
"type": "string",
"description": "Ranges of characters to preserve expressed as regex. The preserved characters will be copied to the output without modification. Important: The preserved characters will not be used in the checkdigit calculation."
},
"weightList": {
"type": "array",
"required": true,
"description": "The list of weights to be used in the checkdigit calculation.",
"items": {
"type": "integer"
}
},
"modulusNumber": {
"type": "integer",
"required": true,
"description": "The modulus number to be used in the checkdigit calculation."
},
"checkDigitIndex": {
"type": "integer",
"required": true,
"description": "The position in the input string to insert the checkdigit, starting with zero for the first digit position. Negative values count backwards from the end of the string, i.e. a value of -2 will be the second to last digit and -1 would be the last. This can account for a variable amount of digits. Non-numeric characters are not counted, only digits apply to the index. If the index is out of bounds the fallback algorithm will mask the input."
},
"calculateChecksumRightToLeft": {
"type": "boolean",
"required": true,
"description": "The direction that the checksum calculation iterates through the input numbers. IBM Mod 11 and Luhn calculate right to left. Verhoeff, Damm and IBAN Mod97-10 calculates left to right."
},
"numDigitsForCheckdigitCalculation": {
"type": "integer",
"required": true,
"description": "The number of digits to use for the checkdigit calculation. If the number of digits used to calculate the checkdigit is less than this, it will be masked using the fallback algorithm. The original checkdigit and and preserved characters are not counted in this number."
},
"swapModulusForZeroRemainder": {
"type": "boolean",
"description": "Some identifiers avoid a first character of zero and have the checknumber in the first position. In this specific case the zero is swapped for the checknumber. Only applicable to identifiers with this specific requirement and a single digit modulus."
},
"checksumCalculationType": {
"type": "string",
"description": "The type of checksum calculation to use. STANDARD uses (modulus - remainder), TFN uses a checkdigit that when added to the weight calculated sum creates a remainder of zero using the provided modulus. Defaults to STANDARD.",
"enum": [
"STANDARD",
"TFN"
]
}
}
}The following JSON formatted input can be used to create a new instance of the framework. Customize it to your specification.
{
"__typename": "AlgorithmFramework",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"extensionSchema": {
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit",
"properties": {
"numericAlgorithm": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the digits of the input value prior to checkdigit(s) calculation.",
"properties": {
"name": {
"type": "string",
"required": true,
"description": "The algorithm instance name, starting with \":\" for instances provided by this plugin"
},
"algorithmMetadata": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference:AlgorithmReferenceMetadata",
"description": "Metadata values passed to the chained algorithm. Can be used to control how automatic type conversions are performed.",
"properties": {
"dateFormat": {
"type": "string",
"description": "The expected date format of a date value being masked."
},
"maxLength": {
"type": "integer",
"description": "The maximum size of the value being masked."
},
"stringMaxLengthEncoded": {
"type": "boolean",
"description": "Boolean value indicating whether the value maxLength represents the maximum Java String length in characters (false), or a byte length limit."
},
"stringCharsetName": {
"type": "string",
"description": "The name of the Charset used to encode string values."
}
}
}
}
},
"alphaNumericAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask alphanumeric body characters prior to checkdigit(s) calculation for alphanumeric identifiers."
},
"fallbackAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the input data if it does not appear in the expected format."
},
"preserveRegex": {
"type": "string",
"description": "Ranges of characters to preserve expressed as regex. The preserved characters will be copied to the output without modification. Important: The preserved characters will not be used in the checkdigit calculation."
},
"weightList": {
"type": "array",
"required": true,
"description": "The list of weights to be used in the checkdigit calculation.",
"items": {
"type": "integer"
}
},
"modulusNumber": {
"type": "integer",
"required": true,
"description": "The modulus number to be used in the checkdigit calculation."
},
"checkDigitIndex": {
"type": "integer",
"required": true,
"description": "The position in the input string to insert the checkdigit, starting with zero for the first digit position. Negative values count backwards from the end of the string, i.e. a value of -2 will be the second to last digit and -1 would be the last. This can account for a variable amount of digits. Non-alphanumeric characters are ignored for indexing. Alphanumeric algorithms index letters and digits; numeric-only algorithms index digits. If out of bounds, the fallback algorithm is used."
},
"calculateChecksumRightToLeft": {
"type": "boolean",
"required": true,
"description": "The direction that the checksum calculation iterates through the input numbers. IBM Mod 11 and Luhn calculate right to left. Verhoeff, Damm and IBAN Mod97-10 calculates left to right."
},
"numDigitsForCheckdigitCalculation": {
"type": "integer",
"required": true,
"description": "The number of digits to use for the checkdigit calculation. If the number of digits used to calculate the checkdigit is less than this, it will be masked using the fallback algorithm. The original checkdigit and and preserved characters are not counted in this number."
},
"swapModulusForZeroRemainder": {
"type": "boolean",
"description": "Some identifiers avoid a first character of zero and have the checknumber in the first position. In this specific case the zero is swapped for the checknumber. Only applicable to identifiers with this specific requirement and a single digit modulus."
},
"checksumCalculationType": {
"type": "string",
"description": "The type of checksum calculation to use. STANDARD uses (modulus - remainder), TFN uses a checkdigit that when added to the weight calculated sum creates a remainder of zero using the provided modulus. Defaults to STANDARD.",
"enum": [
"STANDARD",
"TFN"
]
},
"inputHandlingConfig": {
"type": "object",
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit:InputHandlingConfig",
"description": "Optional configuration for input handling behavior.",
"properties": {
"characterHandling": {
"type": "string",
"description": "Controls how alphabetic characters in the input body are handled during masking and checkdigit calculation. NUMERIC_ONLY falls back to the fallbackAlgorithm when alphabetic characters are found. STANDARD processes alphanumeric bodies using Java's standard character numeric value mapping (A=10...Z=35). ASCII_VALUE_MINUS_48 processes alphanumeric bodies using ASCII value minus 48 (e.g. A=17...Z=42, as required by Brazilian CNPJ). Defaults to NUMERIC_ONLY.",
"enum": [
"NUMERIC_ONLY",
"STANDARD",
"ASCII_VALUE_MINUS_48"
]
},
"invalidInputHandling": {
"type": "string",
"description": "Controls behavior when alphabetic characters are found and characterHandling is NUMERIC_ONLY. FALLBACK_MASK uses the fallbackAlgorithm. ERROR throws NonConformantDataException. Defaults to FALLBACK_MASK.",
"enum": [
"FALLBACK_MASK",
"ERROR"
]
},
"shortInputHandling": {
"type": "string",
"description": "Controls behavior when input is shorter than expected. PAD_LEFT and PAD_RIGHT pad with padCharacter to the required length (only when input contains no formatting characters). FALLBACK routes to the fallbackAlgorithm. Defaults to FALLBACK.",
"enum": [
"FALLBACK",
"PAD_LEFT",
"PAD_RIGHT"
]
},
"padCharacter": {
"type": "string",
"description": "Character to use when padding short input. Defaults to '0'."
},
"trimWhitespace": {
"type": "boolean",
"description": "When true, leading and trailing whitespace is stripped from the input before processing. Useful for CHAR, Fixed-Width, and VSAM columns that deliver space-padded values. Defaults to true."
}
}
}
}
}
}Zachariah Frank [6:17 PM]
Here:
{
"__typename": "AlgorithmFramework",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"extensionSchema": {
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit",
"properties": {
"numericAlgorithm": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the digits of the input value prior to checkdigit(s) calculation.",
"properties": {
"name": {
"type": "string",
"required": true,
"description": "The algorithm instance name, starting with \":\" for instances provided by this plugin"
},
"algorithmMetadata": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference:AlgorithmReferenceMetadata",
"description": "Metadata values passed to the chained algorithm. Can be used to control how automatic type conversions are performed.",
"properties": {
"dateFormat": {
"type": "string",
"description": "The expected date format of a date value being masked."
},
"maxLength": {
"type": "integer",
"description": "The maximum size of the value being masked."
},
"stringMaxLengthEncoded": {
"type": "boolean",
"description": "Boolean value indicating whether the value maxLength represents the maximum Java String length in characters (false), or a byte length limit."
},
"stringCharsetName": {
"type": "string",
"description": "The name of the Charset used to encode string values."
}
}
}
}
},
"alphaNumericAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask alphanumeric body characters prior to checkdigit(s) calculation for alphanumeric identifiers."
},
"fallbackAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the input data if it does not appear in the expected format."
},
"preserveRegex": {
"type": "string",
"description": "Ranges of characters to preserve expressed as regex. The preserved characters will be copied to the output without modification. Important: The preserved characters will not be used in the checkdigit calculation."
},
"weightList": {
"type": "array",
"required": true,
"description": "The list of weights to be used in the checkdigit calculation.",
"items": {
"type": "integer"
}
},
"modulusNumber": {
"type": "integer",
"required": true,
"description": "The modulus number to be used in the checkdigit calculation."
},
"checkDigitIndex": {
"type": "integer",
"required": true,
"description": "The position in the input string to insert the checkdigit, starting with zero for the first digit position. Negative values count backwards from the end of the string, i.e. a value of -2 will be the second to last digit and -1 would be the last. This can account for a variable amount of digits. Non-alphanumeric characters are ignored for indexing. Alphanumeric algorithms index letters and digits; numeric-only algorithms index digits. If out of bounds, the fallback algorithm is used."
},
"calculateChecksumRightToLeft": {
"type": "boolean",
"required": true,
"description": "The direction that the checksum calculation iterates through the input numbers. IBM Mod 11 and Luhn calculate right to left. Verhoeff, Damm and IBAN Mod97-10 calculates left to right."
},
"numDigitsForCheckdigitCalculation": {
"type": "integer",
"required": true,
"description": "The number of digits to use for the checkdigit calculation. If the number of digits used to calculate the checkdigit is less than this, it will be masked using the fallback algorithm. The original checkdigit and and preserved characters are not counted in this number."
},
"swapModulusForZeroRemainder": {
"type": "boolean",
"description": "Some identifiers avoid a first character of zero and have the checknumber in the first position. In this specific case the zero is swapped for the checknumber. Only applicable to identifiers with this specific requirement and a single digit modulus."
},
"checksumCalculationType": {
"type": "string",
"description": "The type of checksum calculation to use. STANDARD uses (modulus - remainder), TFN uses a checkdigit that when added to the weight calculated sum creates a remainder of zero using the provided modulus. Defaults to STANDARD.",
"enum": [
"STANDARD",
"TFN"
]
},
"inputHandlingConfig": {
"type": "object",
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit:InputHandlingConfig",
"description": "Optional configuration for input handling behavior.",
"properties": {
"characterHandling": {
"type": "string",
"description": "Controls how alphabetic characters in the input body are handled during masking and checkdigit calculation. NUMERIC_ONLY falls back to the fallbackAlgorithm when alphabetic characters are found. STANDARD processes alphanumeric bodies using Java's standard character numeric value mapping (A=10...Z=35). ASCII_VALUE_MINUS_48 processes alphanumeric bodies using ASCII value minus 48 (e.g. A=17...Z=42, as required by Brazilian CNPJ). Defaults to NUMERIC_ONLY.",
"enum": [
"NUMERIC_ONLY",
"STANDARD",
"ASCII_VALUE_MINUS_48"
]
},
"invalidInputHandling": {
"type": "string",
"description": "Controls behavior when alphabetic characters are found and characterHandling is NUMERIC_ONLY. FALLBACK_MASK uses the fallbackAlgorithm. ERROR throws NonConformantDataException. Defaults to FALLBACK_MASK.",
"enum": [
"FALLBACK_MASK",
"ERROR"
]
},
"shortInputHandling": {
"type": "string",
"description": "Controls behavior when input is shorter than expected. PAD_LEFT and PAD_RIGHT pad with padCharacter to the required length (only when input contains no formatting characters). FALLBACK routes to the fallbackAlgorithm. Defaults to FALLBACK.",
"enum": [
"FALLBACK",
"PAD_LEFT",
"PAD_RIGHT"
]
},
"padCharacter": {
"type": "string",
"description": "Character to use when padding short input. Defaults to '0'."
},
"trimWhitespace": {
"type": "boolean",
"description": "When true, leading and trailing whitespace is stripped from the input before processing. Useful for CHAR, Fixed-Width, and VSAM columns that deliver space-padded values. Defaults to true."
}
}
}
}
},
"frameworkId": 22,
"frameworkName": "Checkdigit",
"frameworkType": "STRING",
"plugin": {
"__typename": "PluginBase",
"pluginAuthor": "Delphix Engineering",
"pluginId": 7,
"pluginName": "dlpx-core",
"pluginType": "EXTENDED_ALGORITHM"
}
}Checkdigit algorithm extension
The following are configurations for the framework used to create unique instances.
weightList
Array of integers
Defines the weights iterated through by the modulus algorithm when calculating the some from which to derive a checkdigit. For example, IBM MOD11 uses [2, 3, 4, 5, 6, 7]
modulusNumber
Integer
An integer describing the modulus for the algorithm. The built in instances using the framework are based on MOD11 and MOD9.
preserveRegex
String regex expression
Characters to remain unchanged in the input. Used for additional non-calculation digits and alpha numeric characters. For example, this: [0-9]$ will preserve a digit in the last position.
checkDigitIndex
Integer
Where in the input the checkdigit is found, represented with an index starting at zero for the first character. Negative indexes wrap, so an index of -1 will indicate the last character in the input, an index of -2 would be the second to last and so forth. Non-alphanumeric characters are ignored for indexing. When an alphanumeric algorithm is configured, both letters and digits count toward the index position. When NUMERIC_ONLY, only digits count.
numericAlgorithm
AlgorithmInstanceReference
The algorithm used to mask the digits used in the checkdigit calculation. It is only applied to digits, not including the initial checkdigit and any preserved characters. It is configurable but defaults to an instance of CM Digits.
alphaNumericAlgorithm
AlgorithmInstanceReference
The algorithm used to mask alphanumeric body characters prior to checkdigit(s) calculation. Required when input may contain letters. Defaults to CM Alpha-Numeric.
inputHandlingConfig
Object
Optional configuration for input handling behavior. Contains the following sub-fields:
-
characterHandling
Enum
Controls how alphabetic characters are valued during checkdigit calculation. Allowed values are NUMERIC_ONLY, STANDARD, and ASCII_VALUE_MINUS_48.
-
NUMERIC_ONLY (default): alphabetic input routes to fallback
-
STANDARD: A=10...Z=35
-
ASCII_VALUE_MINUS_48: A=17...Z=42, as required by Brazilian CNPJ
-
-
invalidInputHandling
Enum
Controls behavior when alphabetic characters are found and characterHandling is NUMERIC_ONLY. Allowed values are FALLBACK_MASK and ERROR.
-
FALLBACK_MASK (default): routes to fallback algorithm.
-
ERROR: throws NonConformantDataException.
-
-
shortInputHandling
Enum
Controls behavior when input is shorter than expected. Allowed values are FALLBACK, PAD_LEFT, and PAD_RIGHT
-
FALLBACK (default): routes to fallback.
-
PAD_LEFT / PAD_RIGHT: pads with padCharacter to the required length (only when input contains no formatting characters).
-
-
padCharacter
Char
Character used when padding short input. Default: 0.
-
trimWhitespace
Boolean
When true, leading / trailing whitespace is stripped before processing. Useful for CHAR, fixed-width, and VSAM columns that deliver space-padded values. Default: true.
fallbackAlgorithm
AlgorithmInstanceReference
Sometimes things don’t go as planned. The fallback algorithm is used to mask data that does not conform to the expected input structure. It is applied when:
-
The configured index is out of bounds for the input value
-
The number of digits available for calculating the checkdigit is smaller than expected
It is configurable but defaults to an instance of CM Alpha Numeric.
swapModulusForZeroRemainder
Boolean
When the checkdigit value would be zero, substitute the modulus value. This is specifically used for the MOD9 calculation, in the case of a leading checkdigit that is not allowed to be zero. Specifically implemented to support Japanese Corporate Number format.
calculateModulusRightToLeft
Boolean
Some checkdigit algorithms iterate through digits right to left (IBM MOD11, MOD9) when multiplying by weights, others from left to right (MOD97, LUHN). This indicates that configuration.
numDigitsForCheckdigitCalculation
Integer
Ensures the correct amount of digits are used to calculate the new checkdigit in the masked output. An incorrect amount of digits in the input value will trigger use of the fallback algorithm.
checksumCalculationType
Enum String
Allowed values are STANDARD and TFN.
-
STANDARD is the common calculation method of modulus - remainder. Where the remainder is derived from the weighted sum of the input digits divided by the modulus.
-
TFN is a method used by the Australian Tax File Number. The checkdigit is the integer that when added to the weighted sum allows the remainder to be zero.