API Designer and API Workbench Cannot Parse Sample JSON Schema from Tutorial

[dberlind]

Where the RAML 200 tutorial lists a sample schema, the required parameter is listed at the field level like this:

"songTitle": {
     "type": "string",
     "required": true
} 

However, both the API Designer and API Workbench parsers flag it saying that an array is expected for the required parameter. Also, I think there is an extraneous line that says the following:

"required" : true,

that I think will confuse readers (and I wonder myself what this means... for example, when present, does it simply mean that all fields listed are required? The parsers do not reject it.

I believe that the corrected JSON Schema in that case should look like this:

    {
      "type": "object",
      "$schema": "http://json-schema.org/draft-03/schema",
      "id": "http://jsonschema.net",
      "properties": {
        "songTitle": {
          "type": "string"
        },
        "albumId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36
        }
      },
      "required" : ["songTitle", "albumId"]
    }

Additionally, if a JSON example is provided in the RAML that includes non-required fields, I am getting an error in API Designer that says the example does not match the schema. So, taking the SONG example again, I believe the fully corrected JSON Schema (that the parsers will like) should go something like this. Note the addition of the songId field, but the omission of it from the required array:

    {
      "type": "object",
      "$schema": "http://json-schema.org/draft-03/schema",
      "id": "http://jsonschema.net",
      "properties": {
        "songTitle": {
          "type": "string"
        },
        "songId": {
            "type": "string"
        },
        "albumId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36
        }
      },
      "required" : ["songTitle", "albumId"]
    }

Personally, for readability, I like this arrangement (note how I moved the required parameter to be grouped with the rest of the object's definition:

    {
      "type": "object",

      "$schema": "http://json-schema.org/draft-03/schema",
      "id": "http://jsonschema.net",
      "required" : ["songTitle", "albumId"],

      "properties": {
        "songTitle": {
          "type": "string"
        },
        "songId": {
            "type": "string"
        },
        "albumId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36
        }
      }
    }

[sichvoge]

The example you brought up as the "correct" schema is actually not correct. DRAFT-3 is being used here and the required property is not an array. Having required: true basically means all properties are gonna be required.

There is a different problem looking at the current JSON schemas. All properties are also explicitely define required: true which is not working if you defined globally that all are required anyways. So we should change the examples and either do:

• change to draft-4 since the new parser understands that
• remove global required: true
• remove property specific required: true

[dberlind]

Thanks.

I have double checked this in API Workbench and API Designer (in Anypoint).

In API Workbench, "required": true" is flagged as a bad schema when included at the field level in a JSON Schema, but is NOT flagged when included at the global level (for the entire schema). Of course, there are plenty of circumstances where an API would not want to require all fields in the schema.

In API Designer (in Anypoint), "required": true is flagged for bad schema at both the field level and the global level with the error message saying an array is expected.

In both Workbench and Designer, using an array at the global level to say which fields are required is allowed.

It appears as though draft-4 is already the only option that's globally supported across both. So, my suggestion would be to do the following:

• remove global "required": true wherever it appears
• remove field specific "required": true wherever it appears
• add an array at the global level to show how that works (ie: "required": ["field1", "field2"])
• fix API Workbench to flag "required": true at the global level

This screenshot shows API Designer expecting the array: