JSON Over TCP

TCP framing is the real design issue

JSON over TCP is not a transport protocol on its own, it is an application pattern that layers message syntax on top of a byte stream. The important design decision is how the application will decide where one JSON message ends and the next begins, because TCP can split or combine bytes in ways that do not match message boundaries.

That is why the protocol design must define framing explicitly. Without it, parsers can stall, merge adjacent messages, or misread partial content as a complete object, especially when payloads are large, bursty, or produced by multiple writers.

Common framing strategies

The three common approaches are delimiters, length prefixes, and framed envelopes. A delimiter-based design uses a sentinel such as a newline, a length-prefixed design states the size before the body, and an envelope adds metadata around the JSON payload so the receiver can validate structure before parsing.

Each method has trade-offs. Delimiters are simple but require careful escaping and cannot safely carry arbitrary embedded separators unless the format is constrained. Length prefixes are efficient and robust, but they demand strict state handling and bounds checking. Envelopes are more expressive, but they add schema and parsing overhead.

Why stream parsing matters for reliability

Because TCP preserves ordering but not message semantics, the receiver must be able to handle partial reads, coalesced writes, and back-to-back messages. A correct implementation buffers incoming bytes until a full frame is available, then hands exactly one complete JSON document to the parser.

This matters operationally as much as functionally. A parser that assumes a single read equals a single message will fail under normal network conditions, even when the sender is behaving correctly. Good framing is therefore part of protocol correctness, not an optional optimisation.

Where JSON over TCP fits in system design

JSON over TCP is often chosen for internal services, device links, or custom protocols where teams want a human-readable payload and low protocol overhead. It is flexible, but that flexibility shifts responsibility to the application designer, who must define framing, versioning, error handling, and compatibility rules.

In practice, the format works best when the message model is simple and the connection is controlled. When interoperability, public exposure, or long-term protocol evolution matter, teams usually benefit from stricter interface conventions and explicit transport and schema documentation.

Risk and Threat Considerations

Unframed or weakly framed JSON over TCP can create parsing ambiguity, resource exhaustion, and desynchronisation between peers. Those failures are especially risky when the stream is exposed to untrusted input or when the receiver assumes it can trust message size and structure before validation.

Failure mechanism: An attacker or faulty peer can send oversized, partial, or malformed byte sequences that force the application to buffer indefinitely, misparse adjacent messages, or lose framing state.

Impact: The result can be denial of service, message spoofing, dropped transactions, or corrupted application state, especially when parsers retry, resynchronise, or process commands after a boundary error.

Practitioner Guidance

Why practitioners should care: The framing rule is part of the protocol contract, so it should be specified, tested, and enforced with the same care as the JSON schema itself. Teams should treat partial reads, oversized frames, and invalid boundaries as normal failure cases, not edge cases.

What to watch for: The safest implementations make frame parsing explicit, cap message size, and reject ambiguous input early. This is where transport correctness, parser behaviour, and application resilience meet, so review the receiver as carefully as the sender.

Related resources from NHI Mgmt Group

• What is the difference between SMB over NetBIOS on port 139 and SMB directly over TCP/IP on port 445?
• ADB Over TCP Port 5555
• Syslog Over TCP
• Why is visibility over NHIs critical for security?