Native Schemas

Native schemas represent the simplest possible data contracts supported by the MAPS server.
A native schema describes topics whose payload consists of exactly one value, with no object structure and no JSON/Avro/Proto wrapper.

These are commonly used for lightweight telemetry such as:

• /outside/temperature publishing "22.2"
• /device/battery publishing an int8
• /sensor/weight publishing a float

The MAPS server internally provides several built‑in native schema types under the $SYS context to ensure consistent handling of single‑value payloads.

---

1. Supported Native Types

The following native value types are supported:

Type	Description
STRING	UTF‑8 text payload.
NUMERIC_STRING	Numeric value encoded as UTF‑8 string.
INT8	8‑bit signed integer.
INT16	16‑bit signed integer.
INT32	32‑bit signed integer.
INT64	64‑bit signed integer.
FLOAT	32‑bit IEEE‑754 float.
DOUBLE	64‑bit IEEE‑754 double.

Each native schema simply identifies which one of these payload types is expected.

---

2. Examples

Example: String Native Schema

{
  "versionId": "1",
  "description": "Simple string schema",
  "labels": {
    "uniqueId": "native-string-schema",
    "resource": "monitor",
    "interface": "string"
  },
  "format": "native",
  "schema": {
    "type": "STRING"
  }
}

Example: Numeric String Schema

{
  "versionId": "1",
  "description": "Simple numeric string schema",
  "labels": {
    "uniqueId": "native-numeric-schema",
    "resource": "monitor",
    "interface": "numeric"
  },
  "format": "native",
  "schema": {
    "type": "NUMERIC_STRING"
  }
}

---

Example: INT32 Native Schema

{
  "versionId": "1",
  "description": "Integer measurement",
  "labels": {
    "uniqueId": "native-int32-schema",
    "resource": "sensor",
    "interface": "measurement"
  },
  "format": "native",
  "schema": {
    "type": "INT32"
  }
}

---

Server‑Side Notes

• Native schemas are internally implemented using NativeSchemaConfig.
• They carry no schemaBase64 and no structural schema, only a type declaration.
• They are ideal for low‑overhead topics and simple telemetry.
• The server inserts built‑in versions of STRING and NUMERIC_STRING into $SYS.

---

3. When to Use Native Schemas

Use a native schema when:

• Your topic's payload is just a single value.
• You do not need nested fields, JSON objects, arrays, or maps.
• You want maximum payload efficiency, especially for binary INT*, FLOAT, or DOUBLE.
• You are publishing small updates at high frequency.

Do not use native schemas when you need structured data—use JSON, Avro, Protobuf, or CBC instead.