JSON Schema

JSON Schema is probably the most popular schema language. With origins dating back to 2010, JSON Schema was initially built for API validation. Since then, it has found its way into configuration systems across web, cloud, and robotics infrastructure.

Example

Below is an example JSON Schema to give you a flavor of what JSON Schema looks like:

JSON Schema

$schema: "https://json-schema.org/draft/2020-12/schema"
title: Communication Configuration Schema
type: object
required:
  - control_loop_rate_hz
  - watchdog_timeout_ms
  - network
  - logging
  - error_handling
properties:
  control_loop_rate_hz:
    type: integer
    description: Control loop frequency in Hertz
    minimum: 1
    maximum: 1000  
    default: 50
  watchdog_timeout_ms:
    type: integer
    description: Watchdog timeout duration in milliseconds
    minimum: 100   
    maximum: 5000  
    default: 500
  network:
    type: object
    required:
      - max_latency_ms
      - connection_timeout_ms
      - reconnect_attempts
      - reconnect_interval_ms
      - heartbeat_interval_ms
    properties:
      max_latency_ms:
        type: integer
        description: Maximum acceptable network latency in milliseconds
        minimum: 10    
        maximum: 1000  
        default: 100
      connection_timeout_ms:
        type: integer
        description: Connection timeout duration in milliseconds
        minimum: 100    
        maximum: 10000  
        default: 2000
      reconnect_attempts:
        type: integer
        description: Number of reconnection attempts
        minimum: 1
        maximum: 10    
        default: 3
      reconnect_interval_ms:
        type: integer
        description: Interval between reconnection attempts in milliseconds
        minimum: 100    
        maximum: 5000   
        default: 1000
      heartbeat_interval_ms:
        type: integer
        description: Interval between heartbeat messages in milliseconds
        minimum: 50     
        maximum: 1000   
        default: 250
  logging:
    type: object
    required:
      - enable_packet_logging
      - log_level
      - max_log_size_mb
      - retain_logs_days
    properties:
      enable_packet_logging:
        type: boolean
        description: Enable or disable packet logging
        default: true
      log_level:
        type: string
        description: Logging level
        enum: ["debug", "info", "warn", "error"]
        default: "info"
      max_log_size_mb:
        type: integer
        description: Maximum log file size in megabytes
        minimum: 1
        maximum: 1024  
        default: 100
      retain_logs_days:
        type: integer
        description: Number of days to retain log files
        minimum: 1
        maximum: 90    
        default: 30
  error_handling:
    type: object
    required:
      - max_consecutive_failures
      - failure_timeout_ms
      - enable_auto_recovery
    properties:
      max_consecutive_failures:
        type: integer
        description: Maximum number of consecutive failures allowed
        minimum: 1
        maximum: 20    
        default: 5
      failure_timeout_ms:
        type: integer
        description: Timeout duration for failure handling in milliseconds
        minimum: 100    
        maximum: 30000  
        default: 5000
      enable_auto_recovery:
        type: boolean
        description: Enable or disable automatic recovery from failures
        default: true

Although many of JSON Schema’s capabilities are omitted in this example, you’ll find some of the most common keywords, including:

$schema - the JSON Schema draft version
type - the data type of a property
required - the property must exist
properties - the sub-fields of an object
default - the default value of a property
description - a human-readable description of a property
enum - a constrained list of values a property can take
minimum - the minimum value of a property
maximum - the maximum value of a property

For a comprehensive list of JSON Schema keywords, visit the official JSON Schema website. We also find the official test suite highly useful, as it contains a large number of simple JSON Schema examples.

Supported drafts

While JSON Schema has multiple drafts, only Draft 2020-12, the most recent stable draft, is supported. When specifying the $schema keyword in a schema, it must be set to the following value:

$schema: "https://json-schema.org/draft/2020-12/schema"

If the $schema keyword is omitted from a schema, the schema is automatically interpreted as Draft 2020-12.

Custom vocabulary

Miru extends JSON Schema’s vocabulary with the following keywords.

Doubles

JSON Schema’s number type accepts both 1 and 1.0. Some applications care about the difference. For example, ROS 2 rejects 1 for a parameter declared as a double. To require a double, add the x-miru-type: double keyword:

JSON Schema

properties:
  gain:
    type: number
    x-miru-type: double

With this keyword, a number is valid only when it is written with a decimal point or an exponent, such as 1.0 or 1e3. A value of 1 fails validation. The keyword checks only numbers, so keep type: number next to it. double is the only supported value of x-miru-type.

File formats

While JSON Schema was originally built for JSON data, it is not exclusive to JSON. JSON Schema may be uploaded to Miru in the following formats:

JSON (.json)
YAML (.yaml, .yml)

The format of a schema does not need to match the format of the config instance it validates. For example, a YAML-formatted JSON Schema can validate a JSON-formatted config instance. JSON Schemas can validate config instances in the following formats:

JSON (.json)
YAML (.yaml, .yml)

YAML support requires Miru Agent v0.7.0 or newer

Welcome

Fleet

Config Management

Data Uploads

Developers

Administration

JSON Schema

Example

Supported drafts

Custom vocabulary

Doubles

File formats

​Example

​Supported drafts

​Custom vocabulary

​Doubles

​File formats

Example

Supported drafts

Custom vocabulary

Doubles

File formats