# BarcodeFormatSpecification Parameters

The `BarcodeFormatSpecification` object defines format-specific decoding rules and constraints used by barcode reading tasks.

## Example JSON

```json
{
    "BarcodeFormatSpecificationOptions": [
        {
            "Name": "BFS_0",
            "BarcodeFormatIds": ["BF_QR_CODE"],
            "ExpectedBarcodesCount": 512,
            "MirrorMode": "MM_NORMAL",
            "MinResultConfidence": 30
        }
    ]
}
```

## Hierarchical Structure

This tree shows one `BarcodeFormatSpecification` object inside `BarcodeFormatSpecificationOptions`.

```text
BarcodeFormatSpecification
├── Name
├── BarcodeFormatIds
└── Format-specific parameters like ExpectedBarcodesCount
```

## Top-Level Parameters

| Parameter Name | Description |
|:---------------|:------------|
| [`Name`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/name.md) | The unique name of the `BarcodeFormatSpecification` object. |
| [`BarcodeFormatIds`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-format-ids.md) | Specifies which barcode format(s) this specification applies to. |
| [`ExpectedBarcodesCount`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/expected-barcodes-count.md) | Expected number of barcodes to decode. |
| [`MirrorMode`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/mirror-mode.md) | Controls barcode mirroring handling. |
| [`MinResultConfidence`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/min-result-confidence.md) | Minimum confidence threshold for accepted results. |
| [`StandardFormat`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/standard-format.md) | Indicates whether standard format constraints are applied. |
| [`PartitionModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/partition-modes.md) | Defines partitioning strategies during decoding. |
| [`VerifyCheckDigit`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/verify-check-digit.md) | Defines whether to verify check digits. |
| [`IncludeTrailingCheckDigit`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/include-trailing-check-digit.md) | Defines whether to include trailing check digits in text results. |
| [`IncludeImpliedAI01`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/include-implied-ai01.md) | Defines whether to include implied AI(01) for GS1 parsing. |
| [`Code128Subset`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/code128-subset.md) | Specifies the subset strategy for Code 128 decoding. |
| [`MsiCodeCheckDigitCalculation`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/msi-code-check-digit-calculation.md) | Specifies MSI check digit calculation rules. |
| [`RequireStartStopChars`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/require-start-stop-chars.md) | Defines whether start/stop characters are required. |
| [`EnableAddOnCode`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/enable-addon-code.md) | Defines whether add-on codes are decoded with primary barcodes. |
| [`EnableDataMatrixECC000140`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/enable-data-matrix-ecc000-140.md) | Defines whether DataMatrix ECC000-140 variants are enabled. |
| [`DataMatrixModuleIsotropic`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/data-matrix-module-isotropic.md) | Controls isotropic module assumption for DataMatrix. |
| [`DataMatrixSizeOptions`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/data-matrix-size-options.md) | Specifies acceptable DataMatrix symbol size options. |
| [`EnableQRCodeModel1`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/enable-qr-code-model-1.md) | Defines whether QR Code Model 1 decoding is enabled. |
| [`AustralianPostEncodingTable`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/australian-post-encoding-table.md) | Specifies encoding table selection for Australian Post barcodes. |
| [`ReturnPartialBarcodeValue`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/return-partial-barcode-value.md) | Defines whether partial barcode values can be returned. |
| [`FindUnevenModuleBarcode`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/find-uneven-module-barcode.md) | Defines whether to detect barcodes with uneven modules. |
| [`AutoDetectColorInversion`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/auto-detect-color-inversion.md) | Defines whether to auto-detect foreground/background inversion. |
| [`HasVerticalQuietZone`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/has-vertical-quietzone.md) | Defines whether vertical quiet zone is required/assumed. |
| [`HeadModuleRatio`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/head-module-ratio.md) | Defines ratio constraints for leading modules. |
| [`TailModuleRatio`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/tail-module-ratio.md) | Defines ratio constraints for trailing modules. |
| [`MinQuietZoneWidth`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/min-quiet-zone-width.md) | Minimum quiet-zone width requirement. |
| [`MinRatioOfBarcodeZoneWidthToHeight`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/min-ratio-of-barcode-zone-width-to-height.md) | Minimum width-to-height ratio for barcode zones. |
| [`BarcodeZoneMinDistanceToImageBorders`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-zone-min-distance-to-image-borders.md) | Minimum distance from barcode zone to image borders. |
| [`BarcodeZoneWidthToHeightRatioRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-zone-width-to-height-ratio-range-array.md) | Acceptable barcode-zone width/height ratio range(s). |
| [`BarcodeZoneBarCountRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-zone-bar-count-range-array.md) | Acceptable barcode bar-count range(s). |
| [`BarcodeWidthRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-width-range-array.md) | Acceptable barcode width range(s). |
| [`BarcodeHeightRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-height-range-array.md) | Acceptable barcode height range(s). |
| [`BarcodeAngleRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-angle-range-array.md) | Acceptable barcode angle range(s). |
| [`BarcodeTextLengthRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-text-length-range-array.md) | Acceptable decoded-text length range(s). |
| [`BarcodeBytesLengthRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-bytes-length-range-array.md) | Acceptable decoded-byte length range(s). |
| [`BarcodeTextRegexPattern`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-text-regex-pattern.md) | Regex pattern to validate decoded barcode text. |
| [`ModuleSizeRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/module-size-range-array.md) | Acceptable module-size range(s). |
| [`PatchCodeSearchingMargins`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/patch-code-searching-margins.md) | Search margins for Patch Code localization. |
| [`AllModuleDeviation`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/all-module-deviation.md) | Allowed deviation threshold for module consistency checks. |

## Usage Instructions

### Format-Specific Behavior Design

The design purpose of `BarcodeFormatSpecification` is to customize decoding behavior for specific barcode format(s) without affecting other formats.

`BarcodeFormatIds` defines which format(s) the current configuration applies to, and the other parameters in the same object define how those matched format(s) should be processed.

When a setting in `BarcodeFormatSpecification` conflicts with a broader/global setting, the format-specific setting takes priority for the matched formats. For example:

<div align="center">
   <p><img src="assets/example-barcode-format-specification.png" alt="barcode-format-specification" width="60%" /></p>
</div>

Sometimes the captured image is mirrored relative to the real scene. For 2D barcodes, this can cause decoding failures. If only QR Codes are affected, you can set `MirrorMode` specifically for QR Codes:

```json
{
        "Name": "BFS_mirror", 
        "BarcodeFormatIds": ["BF_QR_CODE"], 
        "MirrorMode":"MM_MIRROR"
}
```

### Quick Settings

Based on an existing `BarcodeFormatSpecification` object, you can set `BaseBarcodeFormatSpecificationName` and override only the fields you want to change. For example:

```json
{
    "BarcodeFormatSpecificationOptions": [
        {
            "Name": "BFS_0",
            "BarcodeFormatIds": ["BF_DATAMATRIX"],
            "BinarizationModes": [
                {
                    "Mode": "BM_LOCAL_BLOCK",
                    "BlockSizeX": 5,
                    "BlockSizeY": 5
                }
            ]
        },
        {
            "Name": "BFS_1",
            "BaseBarcodeFormatSpecificationName": "BFS_0",
            "MinResultConfidence": 20
        }
    ]
}
```

In this example, `BFS_1` inherits settings from `BFS_0` and only overrides `MinResultConfidence`.

### Additional Annotations

`BarcodeReaderTaskSetting` defines how a barcode-reading task runs from initialization to finalization. Within it, `BarcodeFormatSpecification` controls format-level decoding behaviors after barcodes are detected.

Default settings are provided for `BarcodeFormatSpecification`, so `BarcodeReaderTaskSetting` can still work even if you do not explicitly configure `BarcodeFormatSpecification` parameters.