#Core Concepts

This page gives the shortest high-level map of Telepact's main ideas before you dive into the detailed guides.

#Message shape

Telepact messages are always two JSON objects in an array:

[headers, body]

  • the first object holds headers

  • the second object holds one request or response payload

Requests usually look like:

[{}, {"fn.example": {"field": 1}}]

Responses usually look like:

[{}, {"Ok_": {"field": 1}}]

For a more complete walkthrough, start with the Quickstart or Learn Telepact by Example.

#Schema role

The Telepact schema is the contract that drives the whole ecosystem.

It defines:

  • function arguments and results

  • reusable structs and unions

  • shared errors and headers

  • what counts as valid requests and responses

That one schema also powers:

  • server-side validation

  • documentation rendering

  • mock servers

  • optional client code generation

  • compatibility checks

For the full language, see the Schema Writing Guide.

#Headers versus body

The body contains the main request or response payload.

Headers are separate metadata that travel alongside that payload. They are where Telepact puts cross-cutting concerns such as auth, request ids, binary negotiation, and select directives.

As a rule of thumb:

  • use the body for domain data and function arguments/results

  • use headers for metadata and transport-adjacent control signals

For more detail, see:

Telepact functions can appear as data types inside other payloads. That lets a server return a pre-populated function call that a client can follow later.

This gives Telepact a hypermedia-like capability without requiring HTTP-specific link formats.

See:

#Select

Telepact supports response shaping through the @select_ header. Clients can ask for fewer fields from a response graph without inventing a separate query language.

See:

#Binary

Telepact can negotiate a compact binary representation at runtime. This means a client can keep a JSON-first development workflow and still upgrade to binary when it wants more efficiency.

See:

#Where to go next