noTopLevelLiterals

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs> <TabItem label="JSON (and super languages)" icon="seti:json"> :::note This rule has been implemented but not released yet. It will be available in the next release. ::: :::caution This rule is part of the [nursery](/linter/#nursery) group. This means that it is experimental and the behavior can change at any time. ::: ## Summary - Diagnostic Category: [`lint/nursery/noTopLevelLiterals`](/reference/diagnostics#diagnostic-category) - This rule doesn't have a fix. - The default severity of this rule is [**information**](/reference/diagnostics#information). - Sources: - Same as [`json/top-level-interop`](https://github.com/eslint/json/blob/main/docs/rules/top-level-interop.md)

How to configure

json

{
	"linter": {
		"rules": {
			"nursery": {
				"noTopLevelLiterals": "error"
			}
		}
	}
}

Description

Require the JSON top-level value to be an array or object.

The JSON specification technically allows any JSON value (object, array, string, number, boolean, or null) to be used as the top-level element of a JSON document. However, some older JSON parsers, especially those created before RFC 7158/4627 was fully adopted, only support objects or arrays as the root element.

Additionally, some security practices (such as those preventing JSON hijacking attacks) rely on the assumption that the top-level value is an object or array. Using an object or array at the top level also provides better extensibility for your data structures over time.

Examples

Invalid

json

"just a string"

<pre class="language-text"><code class="language-text">code-block.json:1:1 <a href="https://biomejs.dev/linter/rules/no-top-level-literals">lint/nursery/noTopLevelLiterals</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Expected the top-level value to be an array or object. > 1 │ "just a string" │ ^^^^^^^^^^^^^^^ 2 │ ℹ Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility. ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

json

true

<pre class="language-text"><code class="language-text">code-block.json:1:1 <a href="https://biomejs.dev/linter/rules/no-top-level-literals">lint/nursery/noTopLevelLiterals</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Expected the top-level value to be an array or object. > 1 │ true │ ^^^^ 2 │ ℹ Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility. ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

json

null

<pre class="language-text"><code class="language-text">code-block.json:1:1 <a href="https://biomejs.dev/linter/rules/no-top-level-literals">lint/nursery/noTopLevelLiterals</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Expected the top-level value to be an array or object. > 1 │ null │ ^^^^ 2 │ ℹ Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility. ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

Valid

json

{
  "property": "value",
  "otherProperty": 123
}

json

["element", "anotherElement"]

json

{}

json

[]

</TabItem> </Tabs>

How to configure

Description

Examples

Invalid

Valid

Related links