Add JSON Schema support

[eemeli]

Discussed previously in #124 and #601 (comment)

At the moment, the schemas that we support all come from the YAML spec, and specify generic types that may exist in a document. This means that for plain nodes in particular, implicit tags are assigned to values based on regexp pattern matches.

As a possible alternative, we could support something like JSON Schema instead, which would allow for defining a document-specific structural schema, which would permit for much greater type safety in our output.

This would make it so that you could parse a YAML doc like

a: true
b: true

with an attached JSON schema

{
  "type": "object",
  "properties": {
    "a": { "type": "string" },
    "b": { "type": "boolean" }
  }
}

and end up with

{ a: 'true', b: true }

but I've not been able to find a sensible way of making that happen.

I would much rather not write yet another JSON schema library, but the few times I've looked, I've found that all of them iterate on the schema rules in order to find any errors in the input data. That doesn't really work well here, as some process is needed that can take the above data and figure out that a: true should result in a string, while b: true should result in a boolean.

For simple examples like this that's of course pretty easy, but JSON schema is pretty powerful, and gets complex rather fast, with multiple rules affecting a single node.

[remcohaszing]

I also went down the path of deserializing data based on JSON schema once, and I can’t recommend it. Schemas get complex fast. For example:

{
  "type": "object"
  "properties": {
    "a": {
      "anyOf": [{ "type": "string" }, { "type": "boolean" }]
    }
  }
}

Now how do you deserialize a: true?

I understand this is an interesting topic to explore, but I recommend against adding this to the yaml package. Schema libraties like Zod offers pretty good capabilities for this, which can be leveraged by passing the output of yaml.parse() into the validation library.

[eemeli]

Now how do you deserialize a: true?

My sense is that this ambiguity almost only arises when another scalar type is combined with { "type": "string" }; enums are the only other case I can think of. Or are there other ambiguous cases?

I think it's solvable by effectively imposing a priority order on types, probably placing enums and then strings at the bottom of the list. That does require communication to users, but it does provide a clear answer that true would end up getting parsed as a boolean value.

[remcohaszing]

Things get weird when you start combining more complex anyOf / oneOf / allOf schemas. (Although you should never use oneOf.)

For example, what do you expect to happen with this schema?

{
  "anyof": [
    {
      "properties": {
        "a": { "type": "boolean" },
        "b": { "type": "string" }
      }
    },
    {
      "properties": {
        "a": { "type": "string" },
        "b": { "type": "boolean" }
      }
    }
  ]
}

a: true
b: true

Also I already see YAML get a lot of hatred from the community. The format is ambiguous, because:

• There are multiple YAML versions, but documents are rarely versioned.
• A lot of people still think of the issues in YAML 1.1 that were resolved in YAML 1.2.
• There are a lot of bad YAML parsers.

For example, when googling yaml, this document is on the first page of search results: https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-from-hell.

I think adding yet another way to interpret YAML, will only add to the confusion.