AiDataGenByLeo/GenericData/ShemaJson/README.md

# Schema for the YAML config file used to generate features (FGBLC schema)

This document describes the format of the configuration file (YAML) used by `AiDataGenByLeo` to know which features to generate and how to arrange them into an output vector or matrix. The formal JSON Schema definition lives in [`Schema.json`](./Schema.json); this README is the plain-language explanation with examples.

## General structure

Every configuration file has three main top-level blocks:

```yaml
name: MyFeatureGenerator
config:
  cols: 3
output:
  type: AIDATALEO_GEN_VECTOR
  contexts: [...]
```

- **`name`** (string): identifier for the generator. Used only for logging/debugging, it doesn't affect the calculation.
- **`config.cols`** (integer, required): number of output columns. It must match the total amount of features/values you declare under `output.contexts`.
- **`output`**: describes the shape and content of the output.

## `output.type`

Defines whether the output is a **vector** or a **matrix**:

- `AIDATALEO_GEN_VECTOR`: each feature contributes a single value per column (even if it internally requests several historical indexes, the final result is a flat vector).
- `AIDATALEO_GEN_MATRIX`: each feature contributes one or more rows within a column. Useful when you want, for example, a series of N candles of the same indicator as input to a model.

If you use `AIDATALEO_GEN_MATRIX`, you must also declare:

- **`output.rows`** (integer): maximum number of rows of the matrix. Not used (ignored) in vector mode.

## `output.contexts`

An array of configuration "blocks". Each context groups one or more features that share the same `mode` and the same index criteria (`idx`).

Each context has:

- **`mode`**: one of `normal`, `custom` or `generate`.
- **`idx`**: depends on `mode` (see below).
- **`data`**: array of features that the `mode`/`idx` is applied to.

### mode: normal

A single candle index, shared by every feature in that context.

```yaml
- mode: normal
  idx: 0
  data:
    - class: Ma_Zona
      prefix: null
      params:
        timeframe: PERIOD_H1
        period: 20
        applied: PRICE_CLOSE
        hide: false
        ma_method: MODE_EMA
```

### mode: custom

A different index per feature declared in `data` (the first element of `idx` corresponds to the first feature in `data`, and so on).

```yaml
- mode: custom
  idx: [0, 1, 2]
  data:
    - class: Rsi_Valor
      params: { timeframe: PERIOD_H1, period: 14, applied: PRICE_CLOSE, hide: false }
    - class: Rsi_Valor
      params: { timeframe: PERIOD_H1, period: 14, applied: PRICE_CLOSE, hide: false }
    - class: Rsi_Valor
      params: { timeframe: PERIOD_H1, period: 14, applied: PRICE_CLOSE, hide: false }
```

### mode: generate

Automatically generates a sequence of indexes from `[start, step, stop]`. Useful for requesting "the last N candles" without listing them one by one.

```yaml
- mode: generate
  idx: [0, 1, 9]     # start=0, step=1, stop=9 -> generates 0,1,2,...,9
  data:
    - class: Ma_Zona
      params:
        timeframe: PERIOD_H1
        period: 20
        applied: PRICE_CLOSE
        hide: false
        ma_method: MODE_EMA
```

In matrix mode, `generate` is the typical way to fill several rows of the same column with a single feature.

### `data[].class`, `prefix` and `params`

- **`class`**: the feature's registered name in the factory (for example `Ma_Zona`, `Rsi_Valor`, `Sar_Distancia`, `News_HasEventToday`). A C++ class must be registered with that exact name via `AIDATAGENBYLEO_REGISTER_CREATOR_FE`.
- **`prefix`**: optional string (or `null`) appended to the column's final name in the CSV. Useful when you repeat the same `class` several times with different parameters and need to tell them apart in the header.
- **`params`**: a free-form object. Its keys depend entirely on the chosen feature (each class defines its own in snake_case, e.g. `timeframe`, `period`, `applied`, `hide`, `period_analysis`). There is no automatic cross-validation between `class` and the keys inside `params`: if you misspell a key or add one that doesn't exist, the feature will silently fall back to its default value.

## Full example — vector

```yaml
name: VectorExample
config:
  cols: 3
output:
  type: AIDATALEO_GEN_VECTOR
  contexts:
    - mode: normal
      idx: 0
      data:
        - class: Ma_Zona
          params: { timeframe: PERIOD_H1, period: 20, applied: PRICE_CLOSE, hide: false, ma_method: MODE_EMA }
        - class: Rsi_Valor
          params: { timeframe: PERIOD_H1, period: 14, applied: PRICE_CLOSE, hide: false }
        - class: TickVolume_Valor
          params: { timeframe: PERIOD_H1 }
```

## Full example — matrix

```yaml
name: MatrixExample
config:
  cols: 1
output:
  type: AIDATALEO_GEN_MATRIX
  rows: 10
  contexts:
    - mode: generate
      idx: [0, 1, 9]
      data:
        - class: Rsi_Valor
          params: { timeframe: PERIOD_M15, period: 14, applied: PRICE_CLOSE, hide: false }
```

This builds a 10-row x 1-column matrix with the RSI value of the last 10 candles.

## Notes / gotchas

- Candle indexes follow the "0 = last closed candle" convention (the current, still-forming candle is never used). If you request `idx: 1`, you're actually asking for the candle before that one.
- The CSV header is built differently depending on the output type: in vector mode it uses each feature's real name (`class` + `prefix`); in matrix mode it uses generic names like `Col_0`, `Col_1`, etc.
- `config.cols` must match the total number of columns your `contexts` end up generating (the library doesn't validate this in a user-friendly way if it doesn't match).

## Validating the YAML/JSON with the schema

`Schema.json` is a standard [JSON Schema](https://json-schema.org/), so you can use it to validate your configuration before running it:

- **VSCode**: if your config file is in `.json` format, you can associate the schema by adding this to your `settings.json`:
  ```json
  "json.schemas": [
    {
      "fileMatch": ["*.fgblc.json"],
      "url": "./GenericData/ShemaJson/Schema.json"
    }
  ]
  ```
  This gives you autocomplete and inline errors right in the editor. If your config is `.yaml`, the [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) lets you do the same thing under `yaml.schemas`.
- **Web validators**: you can paste the contents of `Schema.json` alongside your configuration (converted to JSON if it was in YAML) into tools like [jsonschemavalidator.net](https://www.jsonschemavalidator.net/) to quickly check whether your file matches the expected structure.

> Note: the schema validates the file's _shape_ (which fields exist, their types, what's required), but it does not validate that the keys inside `params` correspond to the feature named in `class` — that is only caught by the library at runtime.