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:

• Invalid type: "ignoredFunction", "ignoredUndefined", "ignoredSymbolValue", "ignoredSymbolKey", "unstableInfinite", "unresolvedClass", "ignoredNotEnumerable", "ignoredArrayProperty"
• Throws an exception: "unsafeCycle", "unsafeBigInt", "unsafeSize", "unsafeException", "unsafeToJSON", "unsafeGetter"

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

Related projects

• safe-json-value: ⛑️ JSON serialization should never fail
• truncate-json: Truncate a JSON string
• guess-json-indent: Guess the indentation of a JSON string

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!