feat: add json string validation action

[hendrikheil]

This PR defines a JSON action to validate strings to be valid json strings (not objects).

Recently an Issue was created to document a valibot schema to validate objects to be json compliant. In that PR @fabian-hiller mentioned a validation action to ensure strings are valid JSON. This PR aims to add that action to valibot.

I'm a bit torn if this action should be called json or jsonString. I lean towards just calling it json, which is why I went with that.

Relevant comment: #933 (comment)

There is another open PR that adds documentation for the valibot schema to validate objects for json compliance here: #936

[fabian-hiller]

Thank you Hendrik! I will review this PR after our v1 RC or stable v1 is out.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
valibot	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 7, 2025 2:47pm

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/valibot@957

commit: 2d3b658

[EskiMojo14]

i think the difficulty with naming is that there's three different things that v.json could do:

• validate that the input is possible to stringify as JSON (jsonable?) (JSON type #933)
• validate that the input is possible to parse as JSON (jsonString?) (JSON type #933 (comment))
• both validate that the input is possible to parse, and transform it to the parsed version (parsedJson?) (feat: add JSON parse and stringify actions #1137)

In my personal experience I've found the last one to be the most useful, which is why I've opened the PR referenced above. I can see the utility of the other two however, so I think naming would just be important to avoid confusion.

I'd generally be against anything that requires parsing the JSON twice and throwing away the first result, which is why I think there's room for both types of action (transform and not transform).

v.pipe(
  v.string(),
  v.jsonString(), // parse happens here, gets thrown away
  v.transform(JSON.parse) // parse happens again
);

The experience with an action that transforms is quite nice, as you can then pipe it to your final expected type:

const prefsSchema = v.object({
  theme: v.picklist(["light", "dark"]),
})
type Prefs = v.InferOutput<typeof prefsSchema>

const prefsFromStorageSchema = v.union([
  v.pipe(v.string(), v.parsedJson(), prefsSchema),
  v.null()
})

const prefsFromStorage = v.parse(prefsFromStorageSchema, localStorage.get("prefs"))
//    ^? Prefs | null

The question also arises as to how much code the two "parse" actions should share, seeing as they're essentially doing the same thing, one is just using the result and the other is ignoring it. Would it make sense for them to throw the same error?

In my personal projects I've actually treated .json more like a method/schema:

const prefsSchema = v.object({
  theme: v.picklist(["light", "dark"]),
})
type Prefs = v.InferOutput<typeof prefsSchema>

const prefsFromStorageSchema = v.union([
  v.json(prefsSchema),
  v.null()
})

const prefsFromStorage = v.parse(prefsFromStorageSchema, localStorage.get("prefs"))
//    ^? Prefs | null

But when opening the PR I opted for an action as it felt more consistent with existing code.