Proper way to describe variant-like structure

[red1939]

Dear community,

I've read quite a few tips and tricks on how to structure JSON schema for non-trivial examples. Sadly, I've got a simple task which seems not so easy to describe in schema.

Imagine std::variant<T> like C++ structure which can be split into 2 parts: common and specialized. The specialized part is not stored as nested property, but flattened. Basing on the type property value (in the common part) the subschema/specialized part will be applied. Examples:

{
  "type": "foo",
  "info": "generic comment",
  "foo_1": 42,
  "foo_2": 666
}

{
  "type": "bar",
  "info": "generic comment v2",
  "bar1": [ 6, 6 ],
  "bar4": 1.4
}

Due to restrictions of Visual Studio Code I am unable to use $dynamicRef and $dynamicAnchor so inheritance/overriding is out of the question... What I've currently done is basically an if-else tree referencing $defs, wrapped into allOf. Sadly there is only one pain point: no ability to use additionalProperties set to false. Neither in the common schema or the specialized one I can put it as being the flat structure each schema will be validated separately marking the JSON file invalid.

I was wondering if I could go with (cursed) oneOf (together with const matcher for the type property) but I've heard that validation error are not the best (and, sadly, I will not be able to control those).

[jdesrosiers]

The good new is, I don't think $dynamicRef/$dynamicAnchor is the solution you're looking for anyway. What you need is unevaluatedProperties. The bad news is, VS Code doesn't support that either 😢.

{
  "allOf": [{ "$ref": "./common" }],
  "properties": {
    "foo_1": { "type": "number" },
    "foo_2": { "type": "number" }
  },
  "unevaluatedProperties": false
}

There are two alternatives you can use that will work in VS Code, but both require some duplication.

The first is that you can use additionalProperties, but you have to put some placeholders for the properties that are declared in the common schema.

{
  "allOf": [{ "$ref": "./common" }],
  "properties": {
    "type": true,
    "info": true,
    "foo_1": { "type": "number" },
    "foo_2": { "type": "number" }
  },
  "additionalProperties": false
}

The second is that you can use propertyNames, to declare all the properties that are allowed in the schema.

{
  "allOf": [{ "$ref": "./common" }],
  "properties": {
    "foo_1": { "type": "number" },
    "foo_2": { "type": "number" }
  },
  "propertyNames": { "enum": ["type", "info", "foo_1", "foo_2"] }
}

I was wondering if I could go with (cursed) oneOf (together with const matcher for the type property) but I've heard that validation error are not the best (and, sadly, I will not be able to control those).

If your target is VS Code, this might not be a problem for you. VS Code will do a lot of guessing what was intended and from what I've seen, it usually makes good guesses and provides reasonable messages. I'd say it's worth trying this method and seeing what results you get. But, if you expect the schema to be used with a standard validator, your users would probably thank you to make your schemas more explicit.