Enums cause Breaking Changes for non-breaking Feature Extensions

[sebbader-sap]

What?

Using Enums for attribute values which shall be open for custom extensions, or later minor releases of the AAS specs, cause errors in older implementations.
Example: https://app.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/schemas/ServiceDescription contains an enum for profiles, which means that the value space is closed. If a company/ecosystem wants to add an own profile (at their own risk that it will not be an official IDTA-backed profile), a client implementation can not parse this.

The example below violates the OpenAPI declaration:

{ 
  "profiles": [ 
      "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
      "https://example.com/aas/my-custom-registry-profile"
   ]
}

How?

Do not use enums wherever we are not 100% sure that the value items are all known. Use a less restrictive (ergo: extendable) type when this is not the case.

Current structure:

    ServiceDescription: 
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001"
              - "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002"
              - "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001"

Possible approach (haven't tested it yet):

    ServiceDescription: 
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            anyOf:
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001"
              -  {}

Source: OAI/OpenAPI-Specification#1552 (comment)

• I have signed the required Developer Certificate of Origin (DCO) already.