# atom.io/foundations/json

Source: docs/source/pages/docs/foundations/json.mdx
URL: /docs/foundations/json

# <low-emphasis>atom.io</low-emphasis>/foundations/json

The JSON value boundary for atom.io: values that can cross persistence,
network messages, process handoff, or a transceiver's JSON form
without changing shape.

### serializable
Source: docs/source/exhibits/foundations/json/serializable.ts

```ts
import { type Json, parseJson, stringifyJson } from "atom.io/foundations/json"

const value = {
	id: `playlist:road-trip`,
	tracks: [`dreams`, `ventura-highway`],
} satisfies Json.Serializable

const encoded = stringifyJson(value)
const decoded = parseJson<typeof value>(encoded)
```

## package contents

<table-wrapper>

| Export | Description |
| --- | --- |
| `primitive` | The JSON primitive union: boolean, number, string, or null. |
| `Json.Serializable` | A recursively JSON-safe value. |
| `Json.Object` | `Json.Object&lt;Key, Value&gt;` is a record whose keys are `Key` and whose values are `Value`. `Value` must be JSON-serializable. |
| `Json.Array` | `Json.Array&lt;Element&gt;` is a readonly array whose members are `Element`. `Element` must be JSON-serializable. |
| `Json.Tree` | Looser JSON-shaped tree types for unknown value inspection. The nested{" "} `Json.Tree.Object&lt;Key, Value&gt;` and{" "} `Json.Tree.Array&lt;Element&gt;` types do not require serializable values. |
| `stringified` | `stringified&lt;JsonValue&gt;` is a string type branded with the JSON value it represents. |
| `parseJson` | `parseJson&lt;JsonValue&gt;(str)` parses a string and returns{" "} `JsonValue` when the input is typed as{" "} `stringified&lt;JsonValue&gt;`. |
| `stringifyJson` | `stringifyJson&lt;JsonValue&gt;(value)` stringifies a JSON value and preserves that value type in the returned `stringified` string. |
| `JsonIO` | A function type whose inputs and output are JSON-serializable. |
| `JsonInterface` | `JsonInterface&lt;Type, JsonValue&gt;` pairs{" "} `toJson` and `fromJson`. `Type` is the runtime value type; `JsonValue` is its serialized JSON form. |
| `isJson` | Runtime predicate for JSON-shaped tree nodes. |
| `JSON_TYPE_NAMES`, `JsonTypeName`,{" "} `JsonTypes`, `JSON_DEFAULTS` | JSON type names and default values by type name. |

</table-wrapper>

## runtime checks

`isJson` accepts JSON-shaped primitives, arrays, and plain objects. It rejects
`undefined`, functions, symbols, bigint primitives, and class-like objects such as
`Set`.

### runtime checks
Source: docs/source/exhibits/foundations/json/runtime-checks.ts

```ts
import { isJson } from "atom.io/foundations/json"

isJson({ ok: true }) // true
isJson(new Set()) // false
```

## defaults

`JSON_DEFAULTS` is useful when a UI needs a starter value for a selected JSON type.

### defaults
Source: docs/source/exhibits/foundations/json/defaults.ts

```ts
import { JSON_DEFAULTS } from "atom.io/foundations/json"

JSON_DEFAULTS.array // []
JSON_DEFAULTS.object // {}
JSON_DEFAULTS.string // ""
```