Arithmetic and relational inter-parameter dependencies and readability concerns

[AML14]

I just checked the proposed format for specifying inter-parameter dependencies with JSON Schema (thanks @darrelmiller and @mkistler!) and, although it may support most dependencies found in our research study (see research paper, Medium post or ASC'22 talk), I see three main drawbacks:

• Arithmetic and relational dependencies are not supported. Or, at least, I don't see any examples. In our experience, arithmetic dependencies are not common at all (e.g., p1 + p2 < 100), although relational dependencies are very common (e.g., p1 < p2). These are very typical for specifying ranges (e.g., minPrice and maxPrice).

• Some dependencies are hard to understand. When reading a description like the Tropo dependency, "if type == 'number' then prefix or number must be specified", I find it really difficult to understand its corresponding translation to the proposed format:

  oneOf:
    - not:
      - properties:
          type:
            enum: ['number']
    - required: [prefix]
    - required: [number]

  What's more, I'm not 100% sure this dependency is correct, since the oneOf keyword forces the use of just one alternative, but using both prefix and number at the same time would still satisfy the dependency (i.e., that combination is an anyOf). In any case, to me, it seems much more natural to write something like IF type=='number' THEN prefix OR number'. Plus, it is less error-prone. These two dependency formats are not exclusive. We could support a simple DSL like that (something similar to our IDL) that translates into this JSON Schema-compatible format.

• Some dependencies are too verbose. Some dependencies like ZeroOrOne or Complex dependencies happen to be too verbose with this format. A clear example is the ZeroOrOne dependency from YouTube: 31 lines for something that could be written as ZeroOrOne(forContentOwner, forDeveloper, forMine, relatedToVideoId). Again, this could also be solved by supporting and intermediary succinct DSL that would translate into this format. In this way, we wouldn't have to reimplement all the validation logic already present in JSON Schema from scratch, but simply the translation DSL -> this format.

All in all, as I was arguing on the Slack channel, it's not only about supporting these dependencies, it's about how we support them. Are developers willing to write 31 lines of code to formally express something like "Specify 0 or 1 of the following parameters: forContentOwner, forDeveloper, forMine, or relatedToVideoId"? I really think we need to make their (our) lives easier.

[handrews]

@AML14 regarding relational and arithmetic constraints, it is possible (in theory) to express such things in JSON Schema, just not with the standard vocabularies. From the most recent draft (unchanged from the previous draft or two, I'm pretty sure):

7.9. Loading Instance Data
While none of the vocabularies defined as part of this or the associated documents define a keyword which may target and/or load instance data, it is possible that other vocabularies may wish to do so.

Keywords MAY be defined to use JSON Pointers or Relative JSON Pointers to examine parts of an instance outside the current evaluation location.

Keywords that allow adjusting the location using a Relative JSON Pointer SHOULD default to using the current location if a default is desirable.

So if you want to say that the maximumAmount parameter, if present, is strictly greater than the minimumAmount parameter, you would need to define a greaterThan keyword like this:

parameterSchema:
  type: object
  required: [minimumAmount]
  properties:
    minimumAmount:
      type: number
    maximumAmount:
      type: number
      greaterThan: 1/minimumAmount  # this is a Relative JSON Pointer, using the instance (not schema) structure

A basic relational vocabulary would not be hard to spec out. I know of at least two JSON Schema implementations that can handle extension vocabularies that use Relative JSON Pointer for instance data access.

[AML14]

Thanks for the clarification. This is pretty straightforward and easy to understand.

[handrews]

(I'm starting separate threads to keep sub-topics distinct)

Regarding difficulty of reading, for "if type == 'number' then prefix or number must be specified", rather than this:

oneOf:
  - not:
    - properties:
        type:
          enum: ['number']
  - required: [prefix]
  - required: [number]

which I agree is incorrect unless the intention was "exactly one of prefix or number must be specified", I would write:

if:
  properties: {type: {const: number}}
then:
  anyOf:
    - required: [prefix]
    - required: [number]

For this sort of thing I like writing the const property on a single line like that. It emphasizes that there is one simple thing happening, even though normally I would write that kind of schema across multiple lines. But once you're used to properties: {<name>: {const: <value>}} as an idiom, this becomes very clear and recognizable.

Some of this is just education on good idiomatic use of modern JSON Schema. The OAS community is still used to draft-04 which was far less expressive than 2020-12.

[handrews]

I was going to make this another thread, but it turns out to be the same thing: idiomatic use of JSON Schema.

Some dependencies are too verbose. Some dependencies like ZeroOrOne or Complex dependencies happen to be too verbose with this format. A clear example is the ZeroOrOne dependency from YouTube: 31 lines for something that could be written as ZeroOrOne(forContentOwner, forDeveloper, forMine, relatedToVideoId).

Egads! That is enormous. JSON Schema has a lot more tools available than laying this out with properties, oneOf, anyOf, not, and required. Using propertyNames+additionalProperties is one of my favorite tricks for restrictions on data sets of uniform types (propertyNames was introduced in draft-06 or -07, so it wasn't available in OAS pre-3.1). And maxProperties and minProperties seem to often be forgotten.

Let's see how concise we can get this:

  "zeroOrOne{?forContentOwner,forDeveloper,forMine,relatedToVideoId}":
    requests:
      constrainedRequest:
        parameterSchema:
          type: object
          propertyNames:
            enum: [forContentOwner, forDeveloper, forMine, relatedToVideoId]
          additionalProperties:
            type: string
          maxProperties: 1

The actual schema here is 6 lines long. 10 if we put each enum value on its own line.

[handrews]

We could support a simple DSL like that (something similar to our IDL) that translates into this JSON Schema-compatible format.

Part of the point of OAS 3.1 using regular JSON Schema was to avoid having tooling vendors having to implement a custom schema format. JSON Schema already has a way to define interoperable extensions, and OAS 3.1 already uses that mechanism to define its additional keywords. I'd first put effort into solving the problems with JSON Schema vocabularies. And education on how to write better schemas (I should really write a book on that... or a blog or something)

[darrelmiller]

To add emphasis to Henry's point about using standard formats, we really want to leverage existing work where ever possible. There is a lot of value to having DSLs for API design and I encourage people to explore complete API design languages that will optimize for the types of APIs being built but compile into an interoperable standard like OpenAPI.

OpenAPI itself should remain simple for simple stuff, but make the tricky stuff possible. It is not a realistic goal to make OpenAPI descriptions simple for every possible scenario. I don't want to sweat the fact that it might take a bunch of lines of JSON schema to describe a complex interdependency. If easy authoring of complex dependencies is important then let's build that feature into an API design language for describing complex APIs.

[AML14]

@darrelmiller while I agree with you on that, our OpenAPI documents will likely be used not only by ourselves, but by many other people, even non API experts. I’m still concerned about readability. The simplified examples that @handrews provided are great, but these are just simple examples of single dependencies. Just imagine the ZeroOrOne dependency was actually something like ZeroOrOne(p1, p2, p3==’A’), i.e., p3 could be combined with p1 or p2 as long as its value !=’A’. How complex would such a dependency be? (I'm actually asking, I don't know.)

Think also about the specification of multiple dependencies. An extreme case is the search operation of the YouTube API, which contains several complex dependencies involving over 20 parameters. Something like this:

x-dependencies:
  - ZeroOrOne(forContentOwner, forDeveloper, forMine, relatedToVideoId);
  - IF forContentOwner==true THEN onBehalfOfContentOwner AND type=='video' AND NOT (videoDefinition OR videoDimension OR videoDuration OR videoLicense OR videoEmbeddable OR videoSyndicated OR videoType);
  - IF forMine==true THEN type=='video' AND NOT (videoDefinition OR videoDimension OR videoDuration OR videoLicense OR videoEmbeddable OR videoSyndicated OR videoType);
  - IF relatedToVideoId THEN type=='video' AND NOT (channelId OR channelType OR eventType OR location OR locationRadius OR onBehalfOfContentOwner OR order OR publishedAfter OR publishedBefore OR q OR topicId OR videoCaption OR videoCategoryId OR videoDefinition OR videoDimension OR videoDuration OR videoEmbeddable OR videoLicense OR videoSyndicated OR videoType);
  - IF eventType OR videoCaption OR videoCategoryId OR videoDefinition OR videoDimension OR videoDuration OR videoEmbeddable OR videoLicense OR videoSyndicated OR videoType OR location THEN type=='video';
  - AllOrNone(location, locationRadius);
  - IF channelType THEN type=='channel';

What would this look like in JSON Schema? Can it be expressed? How complex would it be to understand? IMHO, having one dependency per line improves readability.

I'm not saying that we need to use this particular DSL. Neither am I saying that we don’t leverage existing work, or that we don’t extend JSON Schema. Let’s do it, if that helps improve readability and thus also developer/user experience. In fact, I see two very straightforward ways to approach this issue:

• Extend JSON Schema with a new vocabulary for this specific purpose (supporting all the seven patterns of dependencies from our study in a more succinct way).
• Provide a custom OPTIONAL DSL that simply TRANSLATES into the JSON Schema format of specifying dependencies. This way, tooling vendors can simply disregard this DSL, as it automatically translates to JSON Schema.

[handrews]

I'm definitely not against a DSL that outputs JSON Schema (or any other schema OAS might support in the future). It is also not mutually exclusive with additional JSON Schema vocabularies (necessary at least for relational assertion support).

What I would caution against is using the most complex example as the driver. How may systems have 20-parameter dependencies? How many people really need to understand dependencies at that level? Is the API specification document really the place to implement such constraints?

One guiding principle with JSON Schema is that there's a limit to how much validation you should try to do in JSON Schema. Some people would argue that we're well past that limit, others think we're don't do anywhere near enough to be useful. JSON Schema annotations exist to allow JSON Schema to provide some essential level of validation, and then attach enough information to allow applications to handle the rest.

For example, format is an annotation because even when implementations support it as an assertion, the degree of support varies wildly. "format": "email" in one popular implementation is "validated" by checking to see if it contains an @ character... and that's all.

So an application that wants to validate email addresses but knows that "format": "email" is unreliable can check the annotations and run any field annotated as an email address through additional validation.

So one approach would be to add annotations that express the relational constraints rather than directly validating them. Since the annotation output format is part of the JSON Schema specification, you can easily write a library that consumes the annotation output and performs the additional validation, and expect it to work across JSON Schema implementations (at least those that support at the "basic" output format). Currently, the biggest barrier to using annotation collection and the output format is that, as specified, it is likely to consume a lot of memory. A fix for this is under discussion and one implementation is trying it out to see if it's feasible.

---

Just imagine the ZeroOrOne dependency was actually something like ZeroOrOne(p1, p2, p3==’A’), i.e., p3 could be combined with p1 or p2 as long as its value !=’A’. How complex would such a dependency be? (I'm actually asking, I don't know.)

Let's find out:

  "zeroOrOne{?p1,p2,p3}":
    requests:
      constrainedRequest:
        parameterSchema:
          type: object
          propertyNames:
            enum: [p1, p2, p3]
          additionalProperties:
            type: string
          if:
            $comment: If p3 != A, it can be combined with one other parameter
            required: [p3]
            properties: {p3: {not: {const: A}}}
          then:
            maxProperties: 2
          else:
            maxProperties: 1

Of course, there are always more complex cases, so swatting down a few more cases with reasonably concise schemas doesn't solve the problem. And there is the readability concern. But people really do start understanding JSON Schema better as they work with it, like most systems. And folks working on these specifications have to work with JSON Schema anyway.

[handrews]

I've changed the title of this to make it more distinct from #100, which has become the general discussion for parameter interdependencies. This discussion focuses on more complex dependencies that are worth considering on top of the basics.