JSON Schema Issue for Criterion Object and Criterion Expression Type Object

[frankkilcommins]

Discussed in #335

^{Originally posted by markus-96 March 21, 2025}
Hi, I am trying to understand the Criterion Object and the Criterion Expression Type Object and how they should look like.

A Criterion Object has a field type that can be either a string or a Criterion Expression Type Object. This means, that a valid Criterion Object can be one of the following in JSON notation:

{
    "condition": "hi",
    "context": "$response.body",
    "type": "simple"
}

or:

{
    "context": "$response.body",
    "condition": "hi",
    "type": {
        "type": "jsonpath",
        "version": "draft-goessner-dispatch-jsonpath-00"
    }
}

but not this:

{
    "condition": "hi",
    "context": "$response.body",
    "type": "jsonpath",
    "version": "draft-goessner-dispatch-jsonpath-00"
}

However, the provided schema.json says that the second option is not ok but the third one is. It is said that the schema.json is not the source of truth, but the spec is, could this be one case for this statement?

With that in mind, I would describe a Criterion Object as follows:

{
  "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object",
  "$defs": {
    "criterion-expression-type": {
      "description": "An object used to describe the type and version of an expression used within a Criterion Object",
      "patternProperties": {
        "^x-": true
      },
      "properties": {
        "type": {
          "$ref": "#/$defs/criterion-expression-type-enum",
          "description": "The type of condition to be applied"
        },
        "version": {
          "description": "A short hand string representing the version of the expression type"
        }
      },
      "required": [
        "type",
        "version"
      ],
      "if": {
        "properties": {
          "type": {
            "const": "jsonpath"
          }
        }
      },
      "then": {
        "properties": {
          "version": {
            "$ref": "#/$defs/criterion-json-path-version-enum"
          }
        }
      },
      "else": {
        "properties": {
          "version": {
            "$ref": "#/$defs/criterion-x-path-version-enum"
          }
        }
      },
      "type": "object"
    },
    "criterion-expression-type-enum": {
      "enum": [
        "jsonpath",
        "xpath"
      ],
      "type": "string"
    },
    "criterion-json-path-version-enum": {
      "const": "draft-goessner-dispatch-jsonpath-00",
      "enum": [
        "draft-goessner-dispatch-jsonpath-00"
      ],
      "type": "string"
    },
    "criterion-type-enum": {
      "description": "type of criterion",
      "enum": [
        "simple",
        "regex",
        "jsonpath",
        "xpath"
      ],
      "type": "string"
    },
    "criterion-x-path-version-enum": {
      "enum": [
        "xpath-10",
        "xpath-20",
        "xpath-30"
      ],
      "type": "string"
    }
  },
  "dependentRequired": {
    "type": [
      "context"
    ]
  },
  "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria",
  "patternProperties": {
    "^x-": true
  },
  "properties": {
    "context": {
      "description": "A runtime expression used to set the context for the condition to be applied on",
      "type": "string"
    },
    "condition": {
      "description": "The condition to apply",
      "type": "string"
    },
    "type": {
      "default": "simple",
      "description": "The type of condition to be applied",
      "oneOf": [
        {
          "$ref": "#/$defs/criterion-type-enum"
        },
        {
          "$ref": "#/$defs/criterion-expression-type"
        }
      ]
    }
  },
  "required": [
    "condition"
  ],
  "type": "object",
  "unevaluatedProperties": false
}
```</div>

[frankkilcommins]

The schema for Criterion Object, did not correctly reference Criteria Type Expression Object as a possibly value for Criterion Object's type property.

The schema should more more like the following (snippet only):

{
  "criterion-object": {
    "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object",
    "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria",
    "type": "object",
    "properties": {
      "context": {
        "description": "A runtime expression used to set the context for the condition to be applied on",
        "type": "string"
      },
      "condition": {
        "description": "The condition to apply",
        "type": "string"
      },
      "type": {
        "description": "The type of condition to be applied. Can be a simple keyword or an object with versioning for jsonpath or xpath.",
        "oneOf": [
          {
            "type": "string",
            "enum": ["simple", "regex", "jsonpath", "xpath"],
            "default": "simple"
          },
          {
            "$ref": "#/$defs/criterion-expression-type-object"
          }
        ]
      }
    },
    "required": ["condition"],
    "dependentRequired": {
      "type": ["context"]
    },
    "$ref": "#/$defs/specification-extensions",
    "unevaluatedProperties": false
  },
  "criterion-expression-type-object": {
    "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object",
    "description": "An object used to describe the type and version of an expression used within a Criterion Object",
    "type": "object",
    "properties": {
      "type": {
        "description": "The type of condition to be applied",
        "enum": ["jsonpath", "xpath"]
      },
      "version": {
        "description": "A short hand string representing the version of the expression type",
        "type": "string"
      }
    },
    "required": ["type", "version"],
    "allOf": [
      {
        "if": {
          "required": ["type"],
          "properties": {
            "type": { "const": "jsonpath" }
          }
        },
        "then": {
          "properties": {
            "version": { "const": "draft-goessner-dispatch-jsonpath-00" }
          }
        }
      },
      {
        "if": {
          "required": ["type"],
          "properties": {
            "type": { "const": "xpath" }
          }
        },
        "then": {
          "properties": {
            "version": {
              "enum": ["xpath-10", "xpath-20", "xpath-30"]
            }
          }
        }
      }
    ],
    "$ref": "#/$defs/specification-extensions"
  }
}

[markus-96]

I would suggest the following:

• in the if/then blocks: "type" is always required and can therefore be removed from the if clauses.
• I would also change the definition of version to an enum in all cases, indicating that there could be added more options in the future:

  [...]
              "version": { "enum": ["draft-goessner-dispatch-jsonpath-00"] }
  [...]
  

[jeremyfiel]

I think this is a case of interpretation of the keyword type and a miss on the review of the original spec.

nesting the keyword is probably not the original intention because the same behavior can be achieved by using a single instance of type with the criterion expression object.

This is unnecessary nesting

type:
  type: 
  version:

imo, It makes much more sense to update the spec wording to indicate the type keyword can be an enum string or a criteria expression object. The examples in the spec also show a similar behavior.

[frankkilcommins]

As it stands in the current version, the nesting is expected.

An author must specify a Criterion Expression Type Object if they do not want the following defaults:

• JSONPath as described by [RFC9535]
• XPath as described by XML Path Language 3.1

We could look to flatten the structure in a future revision.