CBC Schema Specification (MAPS Messaging)

This document describes the actual CBC (Compact Binary Coding) schema format used by MAPS Messaging, based on the real implementation in FieldSpecification and the JSON schema produced by the server.

1. Overview

CBC is a bit‑packed binary encoding format.
Schemas define the exact bit layout for messages: there is no inference, no dynamic typing, no guessing.
The schema describes:

• Application metadata
• One or more messages
• A list of fields for each message
• The bit width and rules for each field
• Optional encode/decode expressions
• Nested structures

CBC is designed for constrained links (e.g., NTN, LoRa, satellite links) where every bit counts.

---

2. CBC Schema Structure

{
  "application": "exampleApp",
  "version": "1.0",
  "description": "Example description",
  "messages": [
    { /* message definition */ }
  ]
}

Top‑level fields

Field	Type	Description
application	string	Namespace or owner of this CBC schema
version	string	Human‑readable schema version
description	string	Description of the schema/application
messages	array	List of messages encoded using CBC

---

3. Message Definition

{
  "description": "A basic status message",
  "direction": "UPLINK",
  "name": "heartbeat",
  "messageKey": 65280,
  "fields": [ /* field list */ ]
}

Fields

Field	Type	Description
name	string	Unique message name
direction	string	"UPLINK" or "DOWNLINK"
description	string	Purpose of the message
messageKey	integer	Message identifier on the wire
fields	array	Ordered field specifications

Order matters. Bits are packed exactly in the order displayed.

---

4. Field Specification

The schema uses the JSON object produced by this Java method:

toFieldMap(FieldSpecification f)

Possible field attributes

Name	Type	Meaning
name	string	Field name (only present for children; parent inserts manually)
type	string	uint, int, bitmask, struct, etc.
size	integer	Bit width (required for numeric types)
optional	boolean	Field may be omitted
fixed	boolean (false only)	Appears only when false, meaning field is not fixed-size
description	string	Documentation
decalc	string (expression)	Expression applied when decoding (raw → logical)
encalc	string (expression)	Expression applied when encoding (logical → raw)
min	number/integer	Minimum logical value
max	number/integer	Maximum logical value
enum	object	Mapping "numeric_value": "label"
fields	array	Nested fields (for type: "struct")

Example of encode/decode rules

{
  "name": "latitude",
  "type": "int",
  "size": 18,
  "decalc": "v/1000",
  "encalc": "v*1000"
}

Raw 18‑bit integer is converted to degrees (and back).

---

5. Example CBC Schema (Heartbeat Message)

This is an actual valid MAPS CBC schema, matching your real field model:

{
  "application": "viasatNtnProofOfConcept",
  "version": "1.1",
  "description": "Viasat NB-NTN proof of concept for efficient binary data transport",
  "messages": [{
    "description": "A basic health/config status message for NB-NTN devices.",
    "direction": "UPLINK",
    "name": "heartbeat",
    "messageKey": 65280,
    "fields": [
      { "name": "secOfDay", "type": "uint", "size": 17 },

      { "name": "location", "type": "struct", "optional": true, "fields": [
        { "name": "latitude",  "type": "int", "size": 18, "decalc": "v/1000", "encalc": "v*1000" },
        { "name": "longitude", "type": "int", "size": 19, "decalc": "v/1000", "encalc": "v*1000" }
      ]},

      { "name": "signal", "type": "struct", "fields": [
        { "name": "rsrp",  "type": "int", "size": 9  },
        { "name": "rsrq",  "type": "int", "size": 6  },
        { "name": "sinr",  "type": "int", "size": 6  },
        { "name": "rssi",  "type": "int", "size": 9,  "optional": true },
        { "name": "cellId","type": "uint","size": 32, "optional": true }
      ]},

      { "name": "psmConfig", "type": "struct", "optional": true, "fields": [
        { "name": "tauT3412", "type": "bitmask", "size": 8 },
        { "name": "actT3324", "type": "bitmask", "size": 8 }
      ]},

      { "name": "edrxConfig", "type": "struct", "optional": true, "fields": [
        { "name": "edrxCycle", "type": "bitmask", "size": 4 },
        { "name": "edrxPtw",   "type": "bitmask", "size": 4 }
      ]},

      { "name": "counter", "type": "uint", "size": 16, "optional": true }
    ]
  }]
}

This is the canonical form that matches the current server implementation.

---

6. Summary

CBC is:

• Fully deterministic bit-packed encoding
• Strictly defined in JSON
• Supports nested structs
• Supports optional fields
• Supports encode/decode transforms
• Supports enums
• Already fully implemented in MAPS using FieldSpecification

This document should be used as the authoritative reference for users designing CBC schemas for IoT, NTN, LoRa, or satellite transport.