Combining unevaluatedProperties and ref: #

[bquinn]

Hi all,

Thanks for your work on JSON Schema, work really seems to have picked up a lot since you have people working on it full time.

My question is about whether a particular construct is possible or whether I'm just doing it wrong.

I would like to have a property which allows as its contents anything from the root schema, plus one extra property.

For example, say I have a simple schema defining one property that is required, reqProp, so this is valid:

{
    "reqProp": "blah"
}

and another property recursiveProp which can contain anything from the root schema plus a new property newProp. So this would be valid:

{
    "reqProp": "blah",
    "recursiveProp": {
        "reqProp": "blah",
        "newProp": "foo"
    }
}

I have tried to combine recursion and unevaluated properties to make it work. This is what I came up with:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "minimal-schema",
  "type": "object",
  "title": "Schema for testing recursive references with new properties",
  "description": "",
  "additionalProperties": false,
  "required": ["reqProp"],
  "properties": {
    "reqProp": {
      "title": "Test required property",
      "type": "string"
    },
    "recursiveProp": {
      "title": "Test recursive property",
      "type": "object",
      "allOf": [
        {
          "$ref": "#"
        }
      ],
      "properties": {
          "newProp": {
            "title": "New property that only exists as part of recursiveProp",
            "type": "string"
          }
      },
      "required": ["newProp"],
      "unevaluatedProperties": false
    }
  }
}

But it fails:

% check-jsonschema --schemafile minimal-schema.json test2.json
Schema validation errors were encountered.
  test2.json::$.recursiveProp: Additional properties are not allowed ('newProp' was unexpected)
  test2.json::$.recursiveProp: Unevaluated properties are not allowed ('reqProp' was unexpected)

Am I doing something wrong, or is this not possible with the 2020-12 draft?

[jdesrosiers]

The problem is "additionalProperties": false at the top level. Once you do this, you can no longer add properties using schema composition. We sometimes call this a "closed" schema. The way around this is to define your base schema as a definition ($defs) allowing additional/unevaluated properties and then using schema composition at the top level to "close" the schema with unevaluatedProperties.

{
  "$ref": "#/$defs/base",
  "unevaluatedProperties": false,

  "$defs": {
    "base": { ... }
  }
}

Now, the top level can be "closed" while still having an "open" schema available at #/$defs/base that can be extended.

{
  "$ref": "#/$defs/base",
  "properties": {
    "newProp": { "type": "string" }
  },
  "unevaluatedProperties": false
}

[bquinn]

That's fantastic, thanks so much for your help!

I just tried it and it works beautifully.

For the benefit of others in the future, here's a revised version of my schema using @jdesrosiers suggestions:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "minimal-schema",
  "type": "object",
  "title": "Schema for testing recursive references with new properties",
  "$defs": {
    "base": {
      "properties": {
        "reqProp": {
          "title": "Test required property",
          "type": "string"
        },
        "recursiveProp": {
          "$ref": "#/$defs/base",
          "properties": {
            "newProp": { "type": "string" }
          },
          "unevaluatedProperties": false
        }
      }
    }
  },
  "$ref": "#/$defs/base",
  "unevaluatedProperties": false,
  "required": ["reqProp"]
}

Side note: It seems that this would nicely replace the "coming soon" text at https://json-schema.org/understanding-json-schema/structuring.html#extending-recursive-schemas. If so I'd be happy to help drafting that section of the docs based on this Q&A. Would that be useful?

[jdesrosiers]

It seems that this would nicely replace the "coming soon" text at https://json-schema.org/understanding-json-schema/structuring.html#extending-recursive-schemas.

Actually, that section is intended for documenting dynamic references $dynamicRef/$dynamicAnchor. This topic is covered in the unevaluatedProperties section. Feel free to suggest improvements to that section.