Fields

The chart basically draws a series of values over time. The notion of the value kind or type is called a field. It’s basically metadata describing the data series values’ type (number, string), formatting properties (number of decimals, unit, etc.) and other properties like the field’s name, description, and so on.

The fields are all defined in a JSON file which conforms to the fields.schema.json schema, portions of which reference the main schema chart.schema.json as described in the main chart definition file. This file is embedded in the SDK and cannot be modified, but you can extend it with your own fields (please see the Extending the chart section for more details).

All schema files are available in the schemas folder in the SDK (a modern IDE like Visual Studio Code may automatically validate the JSON files against the schema and provide intellisense and other features).

Here’s an example of a field definition:

{
    "id": "<field_id>",
    "type": "<field_type>",
    "category": "<field_category>",
    "name": "<field_name>",
    "format": "<field_format>",
    "shortName": "<short_field_name>"
}

All saved charts are validated with a schema, the field ids (just like study ids) must be unique.

NB: if you are extending the chart with your custom studies, please ensure that your field ids do not conflict with the existing ones. The easiest way to do that is to use a prefix for your custom studies and fields. Calling the getTaxonomies() method as described here will list all the existing studies and fields (also annotations, fundamentals and curve styles).

Most of the properties of a field are optional. For example, this is the definition of well known field like Close:

{
    "id": "Close"
}

If you don’t provide them, the name and shortName will default to the field id. The name is shown in the dialogs and the shortName is used in the tooltips.

The type property can be one of the following values: Number (the default), String or Date.

The category property is rarely (and internally) used, it’s a way to group fields together. You will likely only ever set this to Study if you provide the custom studies.

The format property is used to influence the formatting (turning the value into a string) the field’s values. It can either be FromMetaData, which is the default and means “the data source will provide appropriate formatting” or one of the following values: AsInteger (a round number), UseMetricUnit (add suffix like K for thousands or M for millions) or AsPercent (a percentage value; for example 0.42 is formatted to 42%).

As an example of FromMetaData formatting, any of the OHLC values for the AAPL will be formatted with 2 decimals, while the Volume field will be formatted as an integer (no decimals). Futures like GC (Gold) will be formatted with 1 decimal, while the ZS (Soybeans) will use fractions (⅛th). There is no inherent thruth to this, it’s just how the data providers provide the data.