CODEWITHSUNDEEP
swaggerapi-designopenapi
C. Derx
C. Derx

Reputation: 326

Remote enum list for value validation - in OpenAPI specification

I am attempting to define schema in OpenAPI 3.0.2 specification. I want one of the properties to validate against list of values.

Normally, I get to do this with enum.

components:
  schemas:
    catalog:
      title: title here
      description: describing it here
      properties:
        catalogitemid:
          description: catalog identifier
          type: string
          enum: 
            - item1347
            - item9081
            - item5720
        catalogitemname:
          description: catalog item name
          type: string
      required:
        - catalogitemid
        - catalogitemname
      additionalProperties: false

But I want this enum list to be a remote YAML/JSON instead.

Reason: This list needs to be updated periodically (2000+ values). And I want to avoid that forces updating this API.

Below $ref approach fails:

components:
  schemas:
    catalog:
      title: title here
      description: describing it here
      properties:
        catalogitemid:
          description: catalog identifier
          type: string
          enum:
            $ref: 'https://remote/path/to/catalog/list.yaml#/components/schemas/catalogitemid/enum'
        catalogitemname:
          description: catalog item name
          type: string
      required:
        - catalogitemid
        - catalogitemname
      additionalProperties: false

Errors:

Line catalog causes

should have required property '$ref'

missingProperty: $ref

should match exactly one schema in oneOf

And line enum causes

should be array

What would be the way to do this?

Upvotes: 3

Views: 3104

Answers (1)

Helen
Helen

Reputation: 97847

"Vanilla" OpenAPI

OpenAPI Specification only allows $ref in certain contexts, not everywhere. It's not not possible to $ref just the enum value list, but you can $ref the entire property schema:

# This won't work
enum:
  $ref: 'https://...'

# This will work
properties:
  catalogitemid:
    $ref: 'https://remote/path/to/enums/catalog-list.yaml'

The example above assumes that the list.yaml file contains:

description: catalog identifier
type: string
enum: 
  - item1347
  - item9081
  - item5720
  ...

Using Preprocessors

That said, there are tools such as json-refs or openapi-preprocessor that can resolve JSON References and JSON Pointers in any places of a document. You could use them to pre-process the original spec from your question, which would produce a valid resolved OpenAPI definition that can then be used with OpenAPI-compliant tools.

Upvotes: 2

Related Questions