Feature Request: Constraint for single occurrence of a property structure in JSON Schema

[MrJarnould]

Problem Statement

The JSON Schema specification currently lacks support for ensuring that a specific property structure is defined once and only once within an object with dynamically named properties. This capability is essential for JSON representations of relational database tables, which require exactly one primary key column.

Reference to Related GitHub Issue

This feature request is related to ongoing discussions, specifically mentioned in json-schema-org/json-schema-spec#1358, which addresses the need to apply the contains keyword to object structures.

JSON Schema (Current)

Here is the schema that demonstrates the current validation approach, which allows dynamic keys to be associated with either a primaryKeyProperty or a textProperty, but lacks the ability to enforce one and only one instance of primaryKeyProperty:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "description": "Defines the structure for an object with dynamic keys, each referencing either a primaryKeyProperty or a textProperty.",
  "patternProperties": {
    "^[\\w -+]+$": {
      "oneOf": [
        { "$ref": "#/$defs/primaryKeyPropertyDef" },
        { "$ref": "#/$defs/textPropertyDef" }
      ]
    }
  },
  "minProperties": 1,
  "unevaluatedProperties": false,
  "$defs": {
    "primaryKeyPropertyDef": {
      "type": "object",
      "properties": {
        "primaryKeyProperty": {
          "type": "object",
          "additionalProperties": false
        }
      },
      "required": ["primaryKeyProperty"],
      "additionalProperties": false
    },
    "textPropertyDef": {
      "type": "object",
      "properties": {
        "textProperty": {
          "type": "object",
          "additionalProperties": false
        }
      },
      "required": ["textProperty"],
      "additionalProperties": false
    }
  }
}

Example JSON Instances

Instance that Should Pass Validation:

{
  "FirstColumn": {
    "primaryKeyProperty": {}
  },
  "SecondColumn": {
    "textProperty": {}
  }
}

Instance that Incorrectly Passes Validation:

{
  "FirstColumn": {
    "primaryKeyProperty": {}
  },
  "SecondColumn": {
    "primaryKeyProperty": {} // comment: it's not currently possible to prevent a second `"primaryKeyProperty"` from being included 
  }
}

The above instance should fail validation because it has more than one occurrence of the primaryKeyProperty structure, which is against the intended constraint.

Limitations of Current Keywords

The existing keywords within JSON Schema do not provide a way to limit the number of occurrences of the primaryKeyProperty structure within an object. The patternProperties and oneOf are currently used to validate individual properties but cannot enforce the rule that primaryKeyProperty must be limited to a single occurrence within the object.

Proposed Solution

To address this limitation, we propose the introduction of a new keyword or the extension of an existing keyword to perform this validation. Possible solutions could be:

• A new keyword, such as objectContains, which would ensure that a specific structure appears exactly once within an object.
• Extending the functionality of the contains keyword to validate that an object contains a particular property structure only once.

Conclusion

Enforcing that a primaryKeyProperty structure appears once and only once within an object's properties is a crucial feature for JSON Schema, enhancing its ability to model certain data structures that resemble relational databases. Thank you to @gregsdennis and @jdesrosiers for their guidance on this issue (https://json-schema.slack.com/archives/C5CF75URH/p1707258032879409).

[jdesrosiers]

This was previously discussed in #1077. We decided to extend contains to also apply to objects. Later, we changed our minds and decided to go with a separate keyword. More info can be found at #1486.

In short, this is happening and we have agreement on how we want it to happen, but it could still be a while until we can put out a new release that includes it.