JSON payloads, types and field meaning

JSON represents typed values in a text interchange format, while a schema defines field meanings, units and treatment of missing or null data.

JSON represents objects, arrays, strings, numbers, booleans and null. A parser can recognize those values without knowing what a particular API field means.

The API's schema supplies the next layer: required fields, units, identifiers and relationships. Valid JSON can still be invalid input for a particular operation.

Types survive the textual representation

An original integration payload is:

{
  "id": "item-A",
  "positionTicks": 1200000000,
  "paused": false,
  "tags": [],
  "artwork": null
}

In this declared schema, positionTicks uses ten million ticks per second, so the value represents 120 seconds. The field names are illustrative integration names; use the documented fields of an actual Emby endpoint.

The ID is a string. The position is a number. The pause state is a boolean, not the string "false". A consumer that treats every nonempty string as true would misinterpret that string.

Missing, null and empty are different observations

Representation What the JSON says
Field absent This object did not supply that field
"artwork": null An explicit null value was supplied
"artwork": "" A string with zero characters was supplied
"tags": [] An array containing no elements was supplied

The schema determines whether omission means unknown, unchanged, unavailable or invalid. JSON does not provide one global interpretation.

Object member names also matter. Id and id are different JSON names even if a particular application applies case-insensitive binding.

A number can exceed a consumer's exact range

A common JavaScript number uses binary64 representation. The integer 9007199254740993, one above 2^53, does not round-trip exactly through that representation: ordinary parsing produces 9007199254740992.

JSON's number grammar does not automatically solve the consumer's precision limit. A schema can use strings for identifiers or another supported representation for values requiring exact large-integer handling. The producer and consumer must agree.

For an Emby integration, retain the documented units and types of positions, IDs and timestamps. Converting a valid payload into a convenient local type can lose meaning even when the syntax remains correct.

See Also

References