## Overview

The Pixxel platform uses a unified **DataType** format for passing data between processing blocks, insights, workflows, and jobs. This page documents all supported data types and their schemas.

---

## Insights

This section explains how to construct input data for running insights (analytical models) on your AOI.

### Using Input Schema from List Blocks API

The easiest way to construct inputs is to use the input schema returned by the [List Blocks API](/api-reference/blocks/list-blocks-insights). Each block includes an `inputs` array that defines the expected structure. You only need to populate the `value` or `stac_url` field for each input.

### Step 1: Get the Block's Input Schema

Call the List Blocks API to get the block specification:

```bash
GET /v0/blocks/insights?name=cropclassification
```

The response includes the `inputs` array for the block:

```json
{
  "blocks": [
    {
      "spec": {
        "name": "cropclassification",
        "version": "1.0.0",
        "inputs": [
          {
            "format": "raster",
            "name": "input_image",
            "type": "url",
            "description": "Input satellite imagery",
            "properties": {
              "bands": ["B02", "B03", "B04", "B08"]
            }
          },
          {
            "format": "date",
            "name": "start_date",
            "type": "string",
            "description": "Analysis start date"
          },
          {
            "format": "date",
            "name": "end_date",
            "type": "string",
            "description": "Analysis end date"
          }
        ]
      }
    }
  ]
}
```

### Step 2: Populate Values

Copy the input structure and add `value` or `stac_url` for each input:

- For **raster** inputs from AOI assets: add `stac_url` and `asset_source`
- For **raster** inputs from insight outputs: add `value` and `asset_source`
- For **date**, **string**, **number** inputs: add `value`

:::note
The `value` field is always a string. The actual data type is determined by the `type` field (e.g., `"type": "number"` with `"value": "0.8"`).
:::

:::warning
**stac_url vs value for raster inputs**:
- Use `stac_url` when the input is from AOI assets (satellite imagery from STAC catalog)
- Use `value` when the input is from a previous insight's output (S3 URLs)
:::

**Example: Using AOI asset as raster input (stac_url)**

```json
{
  "input": [
    {
      "format": "raster",
      "name": "input_image",
      "type": "url",
      "description": "Input satellite imagery",
      "properties": {
        "bands": ["B02", "B03", "B04", "B08"]
      },
      "stac_url": "https://stac.pixxel.space/collections/pixxel-td2/items/TD2_...",
      "asset_source": {
        "id": "asset_12345",
        "type": "raw_mosaic"
      }
    },
    {
      "format": "date",
      "name": "start_date",
      "type": "string",
      "description": "Analysis start date",
      "value": "2024-01-01"
    },
    {
      "format": "date",
      "name": "end_date",
      "type": "string",
      "description": "Analysis end date",
      "value": "2024-06-30"
    }
  ]
}
```

**Example: Using insight output as raster input (value)**

:::note
When using an insight's output as input to another insight, copy the `properties` from the output to your input. This preserves visualization and discretization settings.
:::

```json
{
  "input": [
    {
      "format": "raster",
      "name": "classified_image",
      "type": "url",
      "description": "Input from previous insight",
      "value": "s3://pixxel-insights/outputs/inference-123/result.tif",
      "asset_source": {
        "id": "insight_xyz789",
        "type": "model_output"
      },
      //properties copied from the insight output.properties
      "properties": {
        "bands": ["classification"],
        "dtype": "uint8",
        "visualisation": {
          "type": "discrete",
          "discrete": {
            "1": "#00FF00",
            "2": "#FF0000"
          }
        },
        "discretization": {
          "type": "index",
          "classes": [
            { "name": "Vegetation", "value": "1", "color": "#00FF00" },
            { "name": "Built-up", "value": "2", "color": "#FF0000" }
          ]
        }
      }
    }
  ]
}
```

---

## Asset Source

The `asset_source` field is **required for `raster` and `vector` inputs** to track data lineage.

| Input Source | `asset_source.id` | `asset_source.type` |
|--------------|-------------------|---------------------|
| AOI asset (original imagery/data) | `asset_id` | `raw_mosaic` |
| Insight output (from previous run) | `insight_id` | `model_output` |

### Example: AOI Asset

```json
"asset_source": {
  "id": "asset_abc123",
  "type": "raw_mosaic"
}
```

### Example: Insight Output

```json
"asset_source": {
  "id": "insight_xyz789",
  "type": "model_output"
}
```

---

## Common Mistakes

:::warning
Avoid these common errors when constructing input data:
:::

| Mistake | Correction |
|---------|------------|
| Using `value` instead of `stac_url` for AOI satellite assets | Use `stac_url` for STAC item references |
| Using `stac_url` for insight outputs | Use `value` for S3 URLs from insight outputs |
| Forgetting `asset_source` for raster/vector inputs | Always include `asset_source` for data lineage |
| Wrong `asset_source.type` | Use `raw_mosaic` for AOI assets, `model_output` for insight outputs |
| Missing `type` field | Always specify the value type (`url`, `string`, `number`, `boolean`) |

---

## Complete Example

Here's a complete example showing multiple input types for running an insight:

```json
{
  "name": "Crop Classification Analysis",
  "block": {
    "name": "cropclassification",
    "version": "1.0.0"
  },
  "input": [
    {
      "format": "raster",
      "name": "input_image",
      "type": "url",
      "stac_url": "https://stac.pixxel.space/collections/pixxel-td2/items/TD2_...",
      "asset_source": {
        "id": "asset_12345",
        "type": "raw_mosaic"
      },
      "properties": {
        "bands": ["B02", "B03", "B04", "B08"],
        "source": "pixxel-td2",
        "date": "2024-06-15"
      }
    },
    {
      "format": "date",
      "name": "start_date",
      "type": "string",
      "value": "2024-01-01"
    },
    {
      "format": "date",
      "name": "end_date",
      "type": "string",
      "value": "2024-06-30"
    },
    {
      "format": "number",
      "name": "confidence_threshold",
      "type": "number",
      "value": "0.8"
    }
  ]
}
```