Different types of properties behavior in schemas with allOf

[mtovt]

Hi there! I have a question about different types of properties in schemas with allOf. Faced that different toolings interpret this case in another way. And I want to be sure what is the correct way to implement this is and why.

Please, see the example below.

It seems, there are 3 possible scenarios with different tools I've met:

1. Bar.property1 infers as object
2. Bar.property1 infers as array
3. Validation error

openapi: 3.0.1
info:
  title: example
  description: allOf example
  version: 0.1.0
servers:
  - url: 'https://example.com'
paths:
  '/foo':
    delete:
      responses:
        '200':
          description: OK
components:
  schemas:
    Foo:
      type: object
      properties: 
        property1: 
          type: object
    Bar:
      type: object
      properties:
        property1:
          type: array
          items:
            type: string
      allOf:
        - $ref: '#/components/schemas/Foo'

I've tried to look for the answer in OpenAPI v3.0.1 Schema Object

This object is an extended subset of the JSON Schema Specification Wright Draft 00.

properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.

type - Value MUST be a string. Multiple types via an array are not supported.

The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.

Should we validate the object separately against object and separately against array in that case? Or is another behavior here expected?

Related:
swagger-api/swagger-editor#3732

[mtovt]

It seems I've handled this. I am leaving my findings here. Will be excellent to receive some approval if it is valid. OpenAPI refers JSON Schema which refers JSON.

The terms "object" and "array" come from the conventions of
JavaScript.

Arrays are used to store multiple elements in a single variable. They are a special type of object in JavaScript. (The typeof operator in JavaScript returns "object" for Arrays.)

So I’d say the correct result here is option 2 Bar.property1 should be array here. It is a valid scenario.

[flaksp]

The Bar schema is valid. But it won't work as you expect.

Schema instance (a value you are validating against a schema) is valid only when it was successfully validated agains all keywords in a schema.

Let's say this is a value you are validating against Bar schema:

{
  "property1": []
}

This is how validator will validate the value against your schemas:

• Evaluating /components/schemas/Bar/type keyword: is passed value has type object? Yes.
• Evaluating /components/schemas/Bar/properties:
  • Evaluating /components/schemas/Bar/properties/property1/type keyword: is passed value has type array? Yes.
• Evaluating /components/schemas/Bar/allOf keyword:
  1. Evaluating /components/schemas/Bar/allOf/0/$ref keyword:
     • Evaluating /components/schemas/Foo/type keyword: is passed value has type object? Yes.
     • Evaluating /components/schemas/Foo/properties:
       • Evaluating /components/schemas/Foo/properties/property1/type keyword: is passed value has type object? No.

As you can see, validation will fail because passed JSON is not valid against the single keyword. Because property1 can't hold a value of types array and object at the same time.

It's important to note that allOf keyword is not an inheritance or merge solution. It's like an intersection. A value should be valid against all schemas defined in allOf keyword.

This repository is mostly about OpenAPI spec. You are welcome to ask questions about JSON Schema in official repository discussions on GitHub 🙂

[mtovt]

@flaksp Thanks for your explanations! I'd like to clarify

The Bar schema is valid.

Did you mean here Bar as JSON Schema is valid here? And as OpenAPI this spec is invalid. Correct?

I mostly think that way too, but here I got this one in a different way.

Evaluating /components/schemas/Foo/properties/property1/type keyword: is passed value has type object? No.

Unfortunately, I'm not familiar with JS. But explanation

Arrays are used to store multiple elements in a single variable. They are a special type of object in JavaScript. (The typeof operator in JavaScript returns "object" for Arrays.)

Seems valid to me. As I got it should be valid here, because array subtype of object.
I suppose it may be not about holding different values at the same time, but about validation against all values at the same time. And seems, array passes validation as object in terms of JS.

[flaksp]

Did you mean here Bar as JSON Schema is valid here? And as OpenAPI this spec is invalid. Correct?

Yep, in terms of JSON Schema specification it's valid schema. But it's not valid in terms of logic.

Unfortunately, I'm not familiar with JS. But explanation

Arrays are used to store multiple elements in a single variable. They are a special type of object in JavaScript. (The typeof operator in JavaScript returns "object" for Arrays.)

Seems valid to me. As I got it should be valid here, because array subtype of object.

Technically, almost everything in JavaScript is an object, even strings and numbers 😁 It's pretty confusing explanation. You should not care about this. And it's not mandatory to read JSON RFC to understand JSON Schema and OpenAPI specs.

Any JSON can be copy-pasted to JavaScript source code file and it will be valid code there. The quoted term explains why they picked such syntax for arrays and objects — just because this is how such data types represented in JavaScript files. Just because JSON specification is designed to be syntax-compatible with JavaScript.

[handrews]

This JSON Schema question has been answered, closing.