Interface Control Document

Introduction

The JSON schema provides a structured and machine readable way of defining what a valid configuration is for the FSP CORR software. It formally describes the required field types and constraints to make sure that configuration data supplied to the system is consistent and correct before processing starts. This document is intended for developers and operators who need to understand how configuration files are used and why schema validation is important for the SKA project.

Overview

In the FSP CORR, configuration data is compared using JSON. Each configuration is validated against a schema before it’s applied, preventing a invalid data set (one that doesn’t have the right data or has incomplete data) from entering the system. The schema acts as a checker between the configuration files and the software. It specifies required keys, enforces data types, restricts values to allowed ranges, and defines the structure of arrays and objects. This step in validation reduces runtime errors and gives clear feedback when the configuration file provided doesn’t meet required expectations.

JSON Schemas

FSP ConfigureScan .JSON Example

The table below is auto generated at build time from the python dictionary of the ConfigureScan schema. Bold attributes indicate that the field is required, whereas attributes that are not bold, are not listed as requirements.

FSP-CORR Controller Configuration

Configuration object for the FSP-CORR Controller

type	object
properties
configure_scan	type	object
	properties
	subarray_id	type	integer
		maximum	16
		minimum	1
	fsp_id	type	integer
		maximum	27
		minimum	1
	subarray_vcc_ids	type	array
		items	type	integer
	corr_vcc_ids	type	array
		items	type	integer
	frequency_slice_id	type	integer
		maximum	26
		minimum	1
	fpga_lane_vcc_fs_mapping	type	array
		items	type	object
			properties
			fpga_lane_id	type	integer
			vcc_id	type	integer
			additionalProperties	False
	zoom_factor	type	number
	zoom_window_tuning	type	number
	integration_factor	type	integer
		maximum	10
		minimum	1
	spead_channel_offset	type	number
	channel_averaging_map	type	array
		items	type	array
			items	type	number
			maxItems	2
			minItems	2
		maxItems	20
		minItems	20
	output_link_map	type	array
		items	type	array
			items	type	number
			maxItems	2
			minItems	2
		maxItems	20
		minItems	20
	output_host	type	array
		items	type	array
			items	False
	config_id	type	string
	frequency_band	type	string
		enum	1, 2, 5a, 5b
	band_5_tuning	type	array
		items	type	number
	frequency_band_offset_stream1	type	number
	frequency_band_offset_stream2	type	number
	additionalProperties	False
resampler_delay_tracker	type	object
	properties
	first_input_timestamp_start_offset	type	number
		minimum	0
	additionalProperties	False
fs_sample_rates	type	array
	items	type	object
		properties
		vcc_id	type	integer
			maximum	192
			minimum	1
		fs_sample_rate	type	integer
vcc_id_to_rdt_freq_shifts	type	object
	patternProperties
	^[0-9]*$	type	object
		properties
		freq_down_shift	type	number
		freq_align_shift	type	number
		freq_wb_shift	type	number
		freq_net_lo	type	number
		freq_scfo_shift	type	number
		additionalProperties	False
transaction_id	type	string
additionalProperties	False

FSP ConfigureScan JSON schema success configuration Example

{
  "configure_scan": {
    "subarray_id": 4,
    "fsp_id": 1,
    "subarray_vcc_ids": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24],
    "corr_vcc_ids": [1,2],
    "frequency_slice_id": 2,
    "fpga_lane_vcc_fs_mapping": [
      {
        "fpga_lane_id": 1,
        "vcc_id": 1
      }
    ],
    "zoom_factor": 0,
    "zoom_window_tuning": 0,
    "integration_factor": 1,
    "spead_channel_offset": 2,
    "channel_averaging_map": 
      [[0, 8], [744, 8], [1488, 8], [2232, 8], 
      [2976, 8], [3720, 8], [4464, 8], [5208, 8], 
      [5952, 8], [6696, 8], [7440, 8], [8184, 8], 
      [8928, 8], [9672, 8], [10416, 8], [11160, 8], 
      [11904, 8], [12648, 8], [13392, 8], [14136, 8]],
    "output_link_map": [[0, 1], [744, 1], [1488, 1], [2232, 1], 
      [2976, 1], [3720, 1], [4464, 1], [5208, 1], 
      [5952, 1], [6696, 1], [7440, 1], [8184, 1], 
      [8928, 1], [9672, 1], [10416, 1], [11160, 1], 
      [11904, 1], [12648, 1], [13392, 1], [14136, 1]],
    "output_host": [[1,"unknown"]],
    "config_id": "test config",
    "frequency_band": "5a",
    "band_5_tuning": [5.85, 7.25],
    "frequency_band_offset_stream1": 1,
    "frequency_band_offset_stream2": 1
  },
  "resampler_delay_tracker": {
    "first_input_timestamp_start_offset": 1
  },
  "fs_sample_rates": [{"vcc_id": 1, "fs_sample_rate":220000000}, {"vcc_id": 2, "fs_sample_rate":220000000}],
  "vcc_id_to_rdt_freq_shifts": {
    "1": {
      "freq_down_shift": 2000,
      "freq_align_shift": -46720,
      "freq_wb_shift": 0,
      "freq_net_lo": 0,
      "freq_scfo_shift": -903420
    }, 
    "2": {
      "freq_down_shift": 2000,
      "freq_align_shift": -1386186480,
      "freq_wb_shift": 0,
      "freq_net_lo": 0,
      "freq_scfo_shift": 114156
    }
  }
}

The schema is written in JSON schema draft 2020-12 and implemented in python as a dictionary. This example validates the configure_scan object which contains necessary parameters for running the ConfigureScan command. It validates fields such as subarray_id and other id values that are required and need to be integers within a defined range, it validates arrays like subarray_vcc_id to check for structure and element types, and more. If any of the rules set in the schema aren’t met, validation fails and a clear error message is displayed.