OpenAPIv3: some schema templates do not specify type

[daffinm]

The following code templates do not specify the type, so we get a warning icon in the editor when we are done.

    SimpleSchema:
      properties:
        property:
          type: integer
          format: int64
    SchemaWithRequiredProperty:
      required:
      - property
      properties:
        property:
          type: integer
          format: int64

Additionally, the icon is a warning but the message says "invalid". This is a bit confusing. If its invalid shouldn't it be an error? The spec does not seem to require that type is specified. Not sure what to recommend here.

[coder4life]

Ran into the same issue unfortunately.

[tedepstein]

This should be an easy fix. I've labeled it in-scope for our next sprint, and tagged it as a "good first bug." If anyone would like to take a stab at this and needs guidance, please let us know, and we'll point you to the template source.

[nbhusare]

@tedepstein I can take this up. What is the expected behavior in this case? I am looking at - com.reprezen.swagedit.core.validation.Validator#CheckMissingtype()

[tedepstein]

Thanks, @nbhusare! Any schema template that includes properties should include an additional line specifying type: object to avoid the warning. For example:

    SchemaWithRequiredProperty:
      type: object
      required:
      - property
      properties:
        property:
          type: integer
          format: int64

Please note:

• This applies to schema templates in OpenAPI v2 (Swagger) and v3.
• The OpenAPI v3 schema templates have changed since this was first reported, so you'll need to look at the current templates to see which schemas need to change.
• Most of the schema templates have three variants:
  1. In the schema context, having only the schema definition itself.
  2. In the schemas context, having a property name that is effectively the schema name, with the schema definition as a set of child properties under that property name. (JSON Schema is highly recursive!)
  3. In the properties context, where the schema template is offered as a property subschema. (Again, highly recursive.)

You'll want to check all three of these contexts to make sure that they all have type: object where appropriate.

As noted, there's a validation warning on schemas that include properties without type: object. The warning message currently says:

Invalid definition, object type is missing

We should change it to say

Schema with properties should specify type: object

The updated warning message should apply to OpenAPI v2 (Swagger) and v3.

For background, have a look at the Schema Object documentation in the OpenAPI v3 spec, and the underlying JSON Schema specification.

JSON Schema is focused on validation, so it is constraint-based. The simplest possible schema is an empty object, which allows any value. A schema with a properties constraint, but without an type: object constraint actually allows non-object values such as string or number, and there's where the confusion lies.

API designers tend to think of this typeless schema as an object schema that requires an object value. What it really says is, "The value can be of any type. If it happens to be an object value, any of its properties matching the specified property names must conform to the corresponding property subschemas." So a typeless schema with properties is actually a legal JSON Schema, it just doesn't mean what most people reasonably think it means. That's why we have this warning.