How to Configure Document Scanning and Barcode Reading with a JSON-Based DSL

Mar 31, 2026

A Domain-Specific Language (DSL) is a computer language that’s targeted to a particular kind of problem. Examples of DSLs are CSS, SQL, make, etc.

An important and useful distinction Martin Fowler makes is between internal and external DSLs. Internal DSLs are particular ways of using a host language to give the host language the feel of a particular language, like Jetpack Compose. External DSLs have their own custom syntax and you write a full parser to process them, like JSON and XML.

Dynamsoft Capture Vision is a Data Capture framework which is designed to make it easy to scan documents, read barcodes and recognize text. One of its key features is that we can use a JSON-based DSL to configure the data capture tasks. In this article, we are going to take a look at this DSL.

What you’ll build: A JSON template that configures Dynamsoft Capture Vision to scan a document and read barcodes from the scanned image — all without writing platform-specific code.

Key Takeaways

Dynamsoft Capture Vision uses a JSON-based Domain-Specific Language (DSL) to define data capture workflows for document scanning, barcode reading, and text recognition.
A single JSON template can chain multiple tasks — such as scanning a document and then reading barcodes from the result — with automatic internal image sharing for better performance.
The JSON DSL is cross-platform: the same template works on iOS, Android, Desktop, and Web without platform-specific code changes.
A SimplifiedCaptureVisionSettings programming interface is available to modify DSL settings at runtime from the host language.

Common Developer Questions

How do I write a DSL template to scan a document and read barcodes in one pipeline?
Can I reuse the same Dynamsoft Capture Vision JSON template across Web, iOS, and Android?
What are the advantages and disadvantages of using a JSON DSL versus direct SDK API calls for data capture?

Prerequisites

To follow along with this tutorial, you need:

A modern web browser (Chrome, Firefox, or Edge)
Basic knowledge of JavaScript and JSON
Get a 30-day free trial license for Dynamsoft Capture Vision
Dynamsoft Capture Vision SDK (Document Normalizer v2+ and Barcode Reader v10+)

Compare Direct API Calls vs. JSON DSL Workflow

To understand why the DSL approach is valuable, let’s compare the two methods side by side.

Suppose we want to scan the document and read the barcodes in the following image:

Driver's license

We can use Dynamsoft Document Normalizer and Dynamsoft Barcode Reader to do this. The two SDKs support various platforms like iOS, Android, Desktop and Web. Here, we use the JavaScript version for Web:

let documentNormalizer = await Dynamsoft.DDN.DocumentNormalizer.createInstance(); //requires Dynamsoft Document Normalizer version 1.x
let barcodeReader = await Dynamsoft.DBR.BarcodeReader.createInstance(); //requires Dynamsoft Barcode Reader version 9.x
let img = document.getElementById("image");
let quads = await documentNormalizer.detectQuad(img);
let normalizedImageResult = await documentNormalizer.normalize(img, {
  quad: quads[0].location
});
let normalizedImageAsCanvas = normalizedImageResult.image.toCanvas();
let barcodeResults = await barcodeReader.decode(normalizedImageAsCanvas);

Dynamsoft Capture Vision can work as a router to call Dynamsoft Document Normalizer and Dynamsoft Barcode Reader to achieve the same result.

First, we need to define the task in a JSON DSL.

Define a barcode reading task and a document scanning task.

{
  "BarcodeReaderTaskSettingOptions": [
    {
      "Name": "task-read-barcodes"
    }
  ],
  "DocumentNormalizerTaskSettingOptions": [
    {
      "Name": "task-detect-and-normalize-document"
    }
  ]
}

Define two target ROIs: a whole-image ROI for document scanning and an ROI for barcode reading which is based on the detected document image.

{
  "TargetROIDefOptions": [
    {
      "Name": "roi-detect-and-normalize-document",
      "TaskSettingNameArray": ["task-detect-and-normalize-document"]
    },
    {
      "Name": "roi-read-barcodes",
      "TaskSettingNameArray": ["task-read-barcodes"],
      "Location":
      {
        "ReferenceObjectFilter" : {
          "ReferenceTargetROIDefNameArray": ["roi-detect-and-normalize-document"]
        }
      }
    }
  ]
}

Note: if the Location is not set, the ROI is the whole image.

Define a template named ScanDocumentAndReadBarcode which uses the two target ROIs for processing.

{
  "CaptureVisionTemplates": [
    {
      "Name": "ScanDocumentAndReadBarcode",
      "ImageROIProcessingNameArray": [
        "roi-detect-and-normalize-document","roi-read-barcodes"
      ]
    }
  ]
}

Save the JSON as template.json and then, we can do the same document scanning and barcode reading task with the following JavaScript code:

let router = await Dynamsoft.CVR.CaptureVisionRouter.createInstance();
let response = await fetch("./template.json");
let settings = await response.text();
await router.initSettings(settings);
let results = await router.capture(document.getElementById("image"),"ScanDocumentAndReadBarcode");

We can do a lot more using the JSON DSL, like setting the image processing parameters, specifying which barcode formats to use, etc. You can learn about this in the docs.

PS: Dynamsoft Capture Vision requires Dynamsoft Document Normalizer v2+ and Dynamsoft Barcode Reader v10+.

Evaluate the Advantages and Disadvantages

Using a JSON-based DSL in Dynamsoft Capture Vision has some advantages and disadvantages:

Advantages:

The data capture logic can be shared between different platforms without the need to write platform-specific codes.
Image processing results can be shared internally to improve performance. For example, we don’t need to read images into bytes or convert an image to grayscale twice.
Domain experts can solve specific tasks more efficiently than using a general programming language.

Disadvantages:

There is a learning curve.
Designing and maintaining a DSL is an extra cost.
Not easy to modify the settings using the host language. This is often needed in an interactive scenario, like modifying the boundaries of a scanned document before cropping.

To overcome the disadvantages, Dynamsoft Capture Vision has done the following work:

A programming interface to modify the settings: SimplifiedCaptureVisionSettings
Detailed documentation to help you learn it.

Common Issues and Edge Cases

Template not loading: If initSettings() silently fails, verify the JSON file path is correct and the file is valid JSON. A common mistake is trailing commas in JSON objects, which are not allowed.
Barcode ROI returns empty results: When chaining tasks (e.g., document scan → barcode read), ensure the ReferenceTargetROIDefNameArray in the barcode ROI matches the exact Name of the document scanning ROI. A typo here causes the barcode reader to receive no input image.
Version mismatch errors: Dynamsoft Capture Vision requires Document Normalizer v2+ and Barcode Reader v10+. Using older SDK versions (e.g., DDN v1 or DBR v9) with the CaptureVisionRouter will throw initialization errors.

Frequently Asked Questions

How do I write a JSON DSL template for document scanning and barcode reading?

Define a DocumentNormalizerTaskSettingOptions entry and a BarcodeReaderTaskSettingOptions entry in your JSON template, then reference both through TargetROIDefOptions and a CaptureVisionTemplates entry. The barcode ROI can reference the document ROI so the barcode reader operates on the scanned document image.

Can I modify Dynamsoft Capture Vision DSL settings at runtime?

Yes. Use the SimplifiedCaptureVisionSettings interface to read and update settings programmatically from JavaScript, Java, Swift, or other host languages — without editing the JSON template file directly.

What platforms does the Dynamsoft Capture Vision JSON DSL support?

The same JSON template works across Web (JavaScript), iOS (Swift/Objective-C), Android (Java/Kotlin), and Desktop (C++/.NET). This cross-platform reuse is one of the key advantages of the DSL approach over writing platform-specific API calls.

Source Code

You can find the source code of demos using Dynamsoft Capture Vision in the following repo: https://github.com/tony-xlh/dynamsoft-capture-vision-samples/