Is-json-value NPM

Check if a value is valid JSON.

Hire me

Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.

Features

Detects many types of invalid values with JSON
Returns warning messages to throw or log
Returns invalid properties' path and value

Example

import isJsonValue from 'is-json-value'

const input = { one: true, two: { three: Symbol() } }
input.self = input

// Throws due to cycle with 'self'.
// Also, 'two.three' would be omitted since it has an invalid JSON type.
JSON.stringify(input)

const warnings = isJsonValue(input)
const isValidJson = warnings.length === 0 // false
console.log(warnings)
// [
//   {
//     message: 'Property "two.three" must not be a symbol.',
//     path: ['two', 'three'],
//     value: Symbol(),
//     reason: 'ignoredSymbolValue'
//   },
//   {
//     message: 'Property "self" must not be a circular value.',
//     path: ['self'],
//     value: <ref *1> { one: true, two: [Object], self: [Circular *1] },
//     reason: 'unsafeCycle'
//   }
// ]

if (!isValidJson) {
  // Error: Property "two.three" must not be a symbol.
  throw new Error(warnings[0].message)
}

Install

npm install is-json-value

This package works in both Node.js >=18.18.0 and browsers.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

isJsonValue(input)

input any\ Return value: Warning[]

Returns an array of warnings. If input is valid to serialize as JSON, that array is empty.

Warning

Each warning is an object indicating that a specific property is invalid to serialize as JSON. The same property might have multiple warnings.

message

Type: string

Warning message, like 'Property "example" must not be a symbol.'

path

Type: Array<string | symbol | number>

Path to the invalid property. Empty array if this is the top-level value.

value

Type: unknown

Value of the invalid property.

reason

Type: string

Reason for the warning among:

Warnings

This is the list of possible warnings.

Invalid types

JSON only supports booleans, numbers, strings, arrays, objects and null. Any other type is omitted or transformed by JSON.stringify().

Functions

const invalidJson = { prop: () => {} }
JSON.stringify(invalidJson) // '{}'

Undefined

const invalidJson = { prop: undefined }
JSON.stringify(invalidJson) // '{}'

Symbol values

const invalidJson = { prop: Symbol() }
JSON.stringify(invalidJson) // '{}'

Symbol keys

const invalidJson = { [Symbol()]: true }
JSON.stringify(invalidJson) // '{}'

NaN and Infinity

const invalidJson = { one: Number.NaN, two: Number.POSITIVE_INFINITY }
JSON.stringify(invalidJson) // '{"one":null,"two":null}'

Classes

const invalidJson = { prop: new Set([]) }
JSON.stringify(invalidJson) // '{"prop":{}}'

Non-enumerable keys

const invalidJson = {}
Object.defineProperty(invalidJson, 'prop', { value: true, enumerable: false })
JSON.stringify(invalidJson) // '{}'

Array properties

const invalidJson = []
invalidJson.prop = true
JSON.stringify(invalidJson) // '[]'

Exceptions

JSON.stringify() can throw on specific properties.

Cycles

const invalidJson = { prop: true }
invalidJson.self = invalidJson
JSON.stringify(invalidJson) // Throws: Converting circular structure to JSON

BigInt

const invalidJson = { prop: 0n }
JSON.stringify(invalidJson) // Throws: Do not know how to serialize a BigInt

Big properties

const invalidJson = { prop: '\n'.repeat(5e8) }
JSON.stringify(invalidJson) // Throws: Invalid string length

Infinite recursion

const invalidJson = { toJSON: () => ({ invalidJson }) }
JSON.stringify(invalidJson) // Throws: Maximum call stack size exceeded

Exceptions in `toJSON()`

const invalidJson = {
  prop: {
    toJSON: () => {
      throw new Error('example')
    },
  },
}
JSON.stringify(invalidJson) // Throws: example

Exceptions in getters

const invalidJson = {
  get prop() {
    throw new Error('example')
  },
}
JSON.stringify(invalidJson) // Throws: example

Exceptions in proxies

const invalidJson = new Proxy(
  { prop: true },
  {
    get: () => {
      throw new Error('example')
    },
  },
)
JSON.stringify(invalidJson) // Throws: example