Introduction

When Agents handle JSON, they often need to confirm if an object conforms to a schema and be able to point out where it does not. Simply querying fields is not enough, and relying on direct model judgment is unstable under complex nested structures. dsh-tool-schema turns this into a single tool call: given a schema and data, it returns the validation conclusion, failure paths, schema constraint explanations, and optional default application results.

What is it

dsh-tool-schema is a DSH plugin, located in the repository omdsh-dev/dsh-tool-schema, under the MIT license. It provides a local JSON Schema validation tool with a core focus: validating data, listing failure paths, explaining schema constraints, and safely applying default. The plugin emphasizes zero network, zero dynamic code execution, and runs within fixed resource limits.

Core Features

validate

validate is used to verify if an instance conforms to a given schema.

It returns:

  • Validation conclusion
  • Error location using RFC 6901 instancePath / schemaPath
  • schemaIssues
  • checkedNodes
  • truncated

This action is suitable when full validation results and error paths are needed.

paths

paths only returns failure paths.

It returns:

  • Failure paths
  • Summary of keywords
  • errorCount
  • truncated

If you only need to quickly locate “where it went wrong”, you can use this action to avoid returning excessive complete error information.

explain

explain is used to statically explain schema constraints.

It outputs:

  • Sequence of constraint tree nodes
  • schemaIssues
  • truncated

This action does not rely on specific data and is suitable for first understanding which fields and values the schema itself constrains.

normalize

normalize first deep copies the data and applies explicit default, then performs validation.

It returns:

  • appliedDefaults
  • warnings
  • Complete validate result

It is suitable for scenarios where default values need to be filled before validation, but it does not modify the original input.

Security and Limitations

The plugin’s validation kernel is pure-function style, aiming to avoid executing uncontrollable code.

Main constraints are as follows:

  • Zero network
  • Zero dynamic code execution
  • pattern executes in a terminable worker
  • pattern shares a 1,000ms hard budget to prevent ReDoS
  • Local $ref supports # and #/$defs/<token>, and uses RFC 6901 escaping
  • Supports cycle detection
  • Unsupported schema keywords report unsupported-keyword
  • When strictSchema=true, it fails directly upon encountering an unsupported keyword
  • When strictSchema=false, it validates the supported subset and returns supportedSubsetValid

Resource limits are as follows:

  • data / schema each not exceeding 256 KiB
  • Nesting depth not exceeding 64
  • Schema node count not exceeding 10,000
  • Traversed node count not exceeding 100,000
  • Errors default 100, upper limit 1,000
  • $ref chain not exceeding 64
  • Canonical output not exceeding 1 MiB
  • Truncation occurs and is marked truncated after exceeding limits

Installation and Usage

The following shows the installation method for the web profile.

dsh plugin --profile web add github:omdsh-dev/dsh-tool-schema

After installation, you can check if the plugin appears in the profile configuration:

dsh --profile web --dump-config | grep tool-schema

If using local build artifacts, you can also install via tarball path:

npm pack
dsh plugin --profile web add <npm pack 产物 tarball 路径>

For Windows paths, forward slashes are recommended, for example:

C:/path/to/xxx.tgz

Regarding compatibility, this plugin has been verified to be compatible with DSH 0.1.2-alpha.2. The startup method is as follows:

npx -p @deepseek-ai/dsh@next dsh web

Do not use install -g for global installation.

Note that web and headless are different profiles. dsh run uses the headless profile by default. If you want to trigger this plugin with dsh run, you must ensure the plugin is installed to the corresponding profile.

Typical Usage

After installing to an available profile, you can use the following command to have DSH invoke the schema tool for validation:

dsh run "用 schema 工具验证 {name: 'x', age: 3} 是否符合给定 JSON Schema"

Regarding tool parameters:

  • action is optional: validate, paths, explain, normalize
  • schema is required
  • data is required for validate, paths, normalize
  • strictSchema defaults to true

Use Cases and Notes

Suitable for the following scenarios:

  • Validating JSON data such as API responses, plugin manifests, configuration files, session events
  • Locating schema validation failure paths
  • Statically explaining schema constraints
  • Safely applying explicit default before validation

Usage notes:

  • The plugin runs with the current DSH process; please understand its behavior based on the current dsh process permissions
  • Before installation, check the source code, dependency scope, and MIT license
  • Tool parameters are recorded in session logs; do not pass sensitive data
  • Do not treat unsupported keywords as silent ignore; the plugin will report unsupported-keyword
  • pattern validation has an independent worker budget, but still avoid passing overly large schema and data
  • web installation does not automatically override the headless profile

Conclusion

The value of dsh-tool-schema lies in turning JSON Schema validation into a checkable, locatable, and bounded local tool call. It does not access the network, does not dynamically execute code, and provides clear feedback on error paths, schema issues, default application, and resource limits.

GitHub Repository:

  • https://github.com/omdsh-dev/dsh-tool-schema

This article does not list the community directory page URL because the verified materials do not provide an explicit address to reference.