Unknown keywords annotation

[gregsdennis]

The primary argument against supporting unknown keywords is that, because they're just skipped (or their values collected as annotations), there isn't a good way to catch mis-typed keywords. That leads to unexpected validation results, where a keyword is expected to perform some validation but doesn't because what should have been a keyword wasn't recognized as one.

The proposed solutions to this were to

• put additionalProperties: false in the meta-schema
• disallow unknown keywords entirely

We've opted for the second approach with a little bit of the first (we'll have one open and one closed meta-schema).

But what if we just require an annotation that is a list of the unknown keywords?

{
  "valid": true,
  "evaluationPath": "",
  "schemaLocation": "https://json-everything.net/ac994a0348#",
  "instanceLocation": "",
  "annotations": {
    "$unknownKeywords": [ /* ... */ ]
  }
}

(If the validation is false, then the annotation would appear in droppedAnnotations, or we could require that it's always there.)

Note that this isn't a meta-schema validation. $unknownKeywords as an annotation would be commenting on the schema itself rather than the instance.

I'm going to add this to my implementation as an option and expose it in the online validator so people can play with it.

UPDATE ☝️ is done. Play with it at https://json-everything.net/json-schema, and select the Unknown keyword annotation option on the left.

Examples

Schema:

{
  "$id": "/base",
  "foo": {
    "not_a_schema": true
  },
  "type": "object",
  "properties": {
    "bar": { "type": "string" }
  }
}

Instance:

{"bar": "value"}

Result:

{
  "valid": true,
  "evaluationPath": "",
  "schemaLocation": "https://json-everything.net/base#",
  "instanceLocation": "",
  "annotations": {
    "foo": { "not_a_schema": true },
    "properties": [ "bar" ],
    "$unknownKeywords": [ "foo" ]                         // this is the new annotation
  },
  "details": [
    {
      "valid": true,
      "evaluationPath": "/properties/bar",
      "schemaLocation": "https://json-everything.net/base#/properties/bar",
      "instanceLocation": "/bar"
    }
  ]
}

[jdesrosiers]

I'm glad you included an example, because I wasn't following what you were proposing without it. It's like a virtual annotation keyword. It doesn't actually exist in the schema. It's an interesting idea, but definitely a new behavior, so we shouldn't think carefully about it.

[Relequestual]

The proposed solutions to this were to

• put additionalProperties: false in the meta-schema
• disallow unknown keywords entirely

We've opted for the second approach with a little bit of the first (we'll have one open and one closed meta-schema).

But what if we just require an annotation that is a list of the unknown keywords?

When you say "just", do you mean "as opposed to the other solutions"?

[gregsdennis]

However, unknown property detection is a concern for instances as well and the schema solution (prefixing unknown properties with x-) doesn't work for instances.

I don't follow. The unknown keywords are in the schema. This would apply to instance validation. Look at the example again.

[jdesrosiers]

Sorry. Let me try to explain better. Although I wouldn't drop what we've already decided in favor of this approach for addressing unknown keywords, there's a very similar problem that could benefit form this approach.

{
  "type": "object",
  "properties": {
    "foo": { "type": "number" }
  }
}

{
  "fooo": 42
}

Given this schema, the instance is valid, but only accidentally because there's a misspelling of "foo". Tooling could use your proposed sudo-annotation to more easily detect that "fooo" is an unknown property and warn users that they probably meant "foo".

This was the kind of thing I originally thought you were proposing this to solve. I'm not sure why I thought that because your example was clearly a schema.

[gregsdennis]

You can get that annotation already with additionalProperties: true. But yeah, that would be useful.

[jdesrosiers]

Ah, yes. I hadn't thought about that because I don't support that annotation. That same approach could be used with schema validation as well without needing to introduce a sudo-annotation, right?

[gregsdennis]

If by "schema validation" you mean "by a meta-schema," then, yeah, I suppose it could. But who actually meta-schema-validates schemas? 😏

[gregsdennis]

Another idea would be to update the output format. @jdesrosiers has casually mentioned (somewhere) that the root of the output could house additional information about an evaluation, things like dialect. A list of unknown keywords could be added to that instead of being an annotation.

[gregsdennis]

The decision to not support unknown keywords has resulted in requiring implementations to refuse to process such schemas, which means this proposal is no longer relevant. Closing.