Missing titles for properties and enums in Service Plans' JSON schema

[pkosiec]

Description

In some JSON schemas for Service Plans, there are properties without title property. Also, in enums there are no labels for values, which can be achieved in JSON schema with oneOf.

Reasons

The title property is widely used by JSON schema form rendering libraries as a field label. The suggested change, as well as introducing friendly, human-readable labels for enums, will greatly improve usability on UI.

It's very similar to issue #519.

Examples

• Missing title in alias property for Azure Database for MySQL 5.7-- DBMS Only plans
• Missing title for parentAlias property:

• Missing enum value titles for "Backup redundancy" enum:

---

Expected result
This is how the form based on JSON schema renders when all titles have title specified (as an example: Azure SQL Database 12.0 plans):

[pkosiec]

@jldeen Please take a look. Thank you!

[norshtein]

Hi @pkosiec , thanks for raising that. The first and the second item will be fixed soon. For the third item 'Missing enum value titles for "Backup redundancy" enum', enum is a json array in OSBA's implementation, each element in this array must be a string, and can't be an object, so a title can't be added to the enum value.

[norshtein]

Closed via #652 , feel free to reopen it if you have any question.

[pkosiec]

Hi @norshtein,
Thank you for very fast reaction and your PR! I hope that all titles for all fields are covered now 🙂
Could you please reopen the issue? I'd like to discuss more about the enums.

When it comes to the labels for enum values: yes, it would result in changing the implementation a bit. But not much, and also external API won't change - users will still provide the same instanceCreateParameterSchema.

The definition of the JSON schema for Service Plans would need to be slightly changed.

Instead of having this specification:

{
    "title": "Before",
    "type": "object",
    "required": [
      "firstName",
      "lastName"
    ],
    "properties": {
        "backupRedundancy": {
            "default": "local",
            "description": "Specifies the backup redundancy",
            "enum": ["local", "geo"],
            "title": "Backup redundancy",
            "type": "string"
          }
    }
}

We could have:

{
    "title": "After",
    "type": "object",
    "properties": {
      "backupRedundancy": {
        "default": "geo",
        "description": "Specifies the backup redundancy",
        "oneOf": [
          {
            "enum": ["local"],
            "title": "Local Label"
          },
          {
            "enum": ["geo"],
            "title": "Geo Label"
          }
        ],
        "title": "Backup redundancy",
        "type": "string"
      }
    }
  }

So I guess internal types and the implementation of converting provided schema would be modified, but it will bring many benefits when it comes to the UI usability.

Cheers!

[norshtein]

Hi @pkosiec, is the behavior defined by any standard? It will make us in a dilemma if every organization proposes a different implementation... Or you may generate a label at frontend layer for every element in enum array.

[pkosiec]

Hello @norshtein,

This is 100% valid JSON schema. And this is currently the only way how to define labels for enum values - see json-schema-org/json-schema-spec#57.

I've checked quickly front-end libraries and I tested front-end libraries for Angular & React, which support oneOf rendering as enum with nice labels:
https://github.com/hamzahamidi/angular6-json-schema-form
https://github.com/mozilla-services/react-jsonschema-form

Generating labels on front-end side is not a best option, as for example converting geo to Geo still doesn't say much to the end user.

[norshtein]

In #655 , which is another case of enum, "enum" is an array of string. In this issue, how enum values are presented differs. It makes the StringPropertySchema in OSBA inconsistent. So adding a title for enum values may not be supported for now.

[pkosiec]

What do you mean by another case of enum? The #655 issue is about converting string property to enum one. I didn't want to put two ideas in one issue, so I gave there (in #655) an example how the enum would look like after conversion right now - to be 100% consistent with others enums you already have.

But, here, in this issue, the idea is to replace every enum with anyOf, as in the example given above. So yes, the location enum would be eventually replaced with anyOf as well and there would be no inconsistency.

Here's another example for location property after changes:

{
  "location": {
    "default": "eastasia",
    "oneOf": [
      { "enum": ["eastasia"], "title": "Title" },
      { "enum": ["southeastasia"], "title": "Title" },
      { "enum": ["centralus"], "title": "Title" },
      { "enum": ["eastus"], "title": "Title" },
      { "enum": ["eastus2"], "title": "Title" },
      { "enum": ["westus"], "title": "Title" },
      { "enum": ["northcentralus"], "title": "Title" },
      { "enum": ["southcentralus"], "title": "Title" },
      { "enum": ["northeurope"], "title": "Title" },
      { "enum": ["westeurope"], "title": "Title" },
      { "enum": ["japanwest"], "title": "Title" },
      { "enum": ["japaneast"], "title": "Title" },
      { "enum": ["brazilsouth"], "title": "Title" },
      { "enum": ["australiaeast"], "title": "Title" },
      { "enum": ["australiasoutheast"], "title": "Title" },
      { "enum": ["southindia"], "title": "Title" },
      { "enum": ["centralindia"], "title": "Title" },
      { "enum": ["westindia"], "title": "Title" },
      { "enum": ["canadacentral"], "title": "Title" },
      { "enum": ["canadaeast"], "title": "Title" },
      { "enum": ["uksouth"], "title": "Title" },
      { "enum": ["ukwest"], "title": "Title" },
      { "enum": ["westcentralus"], "title": "Title" },
      { "enum": ["westus2"], "title": "Title" },
      { "enum": ["koreacentral"], "title": "Title" },
      { "enum": ["koreasouth"], "title": "Title" },
      { "enum": ["francecentral"], "title": "Title" },
      { "enum": ["francesouth"], "title": "Title" },
      { "enum": ["australiacentral"], "title": "Title" },
      { "enum": ["australiacentral2"], "title": "Title" }
    ],
    "description": "The Azure region in which to provision applicable resources.",
    "title": "Location",
    "type": "string"
  }
}

[zhongyi-zhang]

It makes sense to me. Reopening the issue.
But we have to work on some other very high priority items now. So it might not be addressed in short time :(. And of course if you have interest in it, your contribution would be super appreciated!

[piotrmiskiewicz]

I've prepared a PR which introduced the oneOf field in schemas: #665

[zhongyi-zhang]

Closed via #665.