Glossary

JSON

JSON is a common data notation for HTTP APIs, configuration files and integration messages. The format defines how to write the text; it does not say which fields are required, who may send the message or what its values mean.

Short definition

Data transport in text form, not a complete application contract.

A JSON document contains one value: an object, array, string, number, Boolean or null. An object records name-value pairs in quotation marks, while an array holds ordered values. Its small set of constructs makes the format easy to process in browsers, PHP, database tools and external APIs.

Valid JSON is not necessarily a valid application message. An object with a price field can be syntactically correct while still having an unexpected type, missing a currency or violating a business rule. In addition to parsing JSON, an API therefore validates the schema, permissions, organisation context and relationship with current data.

What it is used for

Passing data among clients, APIs, queues and configuration

JSON works well for a structured message when every participant understands its contract and limits.

the HTTP request and response of a REST API, such as an order, product or validation error
a webhook payload and a message passed through an integration queue
frontend build or tool configuration where a more complex language is unnecessary
a stored read model or document with a clearly defined schema, version and search requirements
a logged structured event that can later be filtered and analysed

Practical example

An order webhook that separates the format from the rules

A carrier sends JSON containing an order identifier and shipment status. The recipient first verifies the HMAC signature of the HTTP request, decodes the JSON and validates that the event is supported. It then finds the order in the current tenant and stores the new information idempotently. Valid JSON with a foreign orderId does not by itself authorize a change.

The amount item here is an integer value in hellers, while the currency is stated separately. The integration therefore does not rely on different decimal rounding by the sender and recipient.

{
  "event": "shipment.delivered",
  "orderId": "ord_8f2c",
  "amount": 129900,
  "currency": "CZK"
}

How it works

From an HTTP body to verified application input

Parsing is only the first step. The application must distinguish a syntax error, invalid data and an unauthorized operation.

Receiving the message The server checks the HTTP method, Content-Type, body size and, where applicable, the webhook signature before passing data to the application.
Decoding A JSON parser converts the text into structures in a given language. Invalid quotation marks, commas or encoding cause a syntax error.
Contract validation The application checks required fields, data types, ranges and unknown values. For a public API, this contract is documented and maintained through versioned changes.
Authorization and business rules Even well-validated JSON must not change an order without the correct user, tenant and current database state.
Response and observability The server returns a structured response or safe error. Logs store a traceable identifier rather than an unlimited copy of the entire sensitive payload.

Fundamental properties

Both sides need to understand the data types and precision.

JSON is not the object model of any one language. Converting between the format and application types requires deliberate rules.

Objects and arrays

An object has named members, while an array preserves the order of values. Object member names are strings in double quotation marks; standard JSON does not permit comments or trailing commas.

Strings and UTF-8

JSON text is transported as UTF-8 in the open ecosystem. Character escaping handles quotation marks and control characters but does not take responsibility for safe HTML rendering.

Numbers and money

JSON has no distinct decimal type. When transferring prices, the currency and representation must be agreed, such as integer minor units or a string, to prevent floating-point errors.

null, missing and default values

A missing field, null and an empty string can have different meanings. The contract must define when a field is optional, when a value can be cleared and when input is invalid.

Content-Type

An HTTP message containing JSON commonly uses application/json. The header helps both the client and server select a parser but does not validate the data.

Benefits and limitations

A simple format that needs a precisely defined interpretation.

Benefits

broad support across browsers, PHP and integration services
a readable structure for both debugging and documentation
natural object and array support for ordinary HTTP messages
easy transfer to a log or queue when size is reasonably limited

Risks and mistakes

valid syntax does not imply valid business input
numbers without agreed semantics can corrupt prices, identifiers or precision
a large or deeply nested payload can exhaust memory and complicate logging
unescaped JSON inserted into HTML or JavaScript context can introduce a security vulnerability
unknown fields and unversioned semantic changes break integration clients

Where to draw the line

Use it for data, not as a substitute for types, validation and authorization.

JSON is practical for APIs and integration messages when the maximum size, contract version, required and optional fields, and error behaviour are also defined. For streaming large imports, binary files or extremely large datasets, another format or batch processing may be more suitable than a single large JSON request.

When accepting untrusted JSON, the request body must be limited, decoding must check for errors and the structure must be validated before values reach the database or domain logic. JSON notation itself does not provide security; HTTPS, authentication, authorization, duplicate-delivery protection and safe logging are also required.

What to consider

Version the contract and return machine-readable errors.

Data exchange works over the long term only when both sides understand the structure in the same way.

specify application/json and reject an unreadable or unreasonably large request body
validate required fields, data types, ranges, enum values and dependencies between fields
define the representation and time zone clearly for money, time and identifiers
do not return an internal exception or an entire sensitive payload in an error response or log
document the contract through OpenAPI or another source of truth and introduce changes compatibly
test invalid syntax, missing fields, unknown events and repeated delivery of an integration message

Common questions

What JSON does and does not express

Is JSON an API?

No. JSON is a data format. An API additionally defines endpoints, methods, authentication, permissions, error states and the meaning of individual fields.

Is OpenAPI the same as JSON?

No. OpenAPI is a specification for describing HTTP APIs and can be written as JSON or YAML. An ordinary JSON document does not automatically describe an entire API.

Can I send a price as a decimal number in JSON?

Yes, but the contract must define precision and rounding. Money is often represented as an integer in the smallest currency unit or as a precisely defined string.

Does JSON protect against attacks?

No. The format does not provide HTTPS, signatures, authentication, authorization or business-rule validation. Input must be limited and verified like any other untrusted data.

How I work with integration data

I connect the data format with the contract, validation and secure event processing.

For API, marketplace and e-commerce integrations, I address message structure alongside authentication, idempotency, retries and traceable failures.

How I work with APIs and integrations Discuss your project without obligation