Extended JSON Metadata with Swagger/OpenAPI

Question

I’m searching for a way to declare extended metadata for JSON objects used in an API which is specified using Swagger/OpenAPI (or something similar if there is another format supporting the requested features).

The idea is to use this metadata to automatically/partially generate user interfaces for editing this data.

A list of the requested features:

• Multilingual support for user readable information like name, description, placeholder, examples – the name and description of the API specification itself might be different than what the end user of for example a CRUD editor should see.

• Validation Metadata
  I know that there a various fields in Swagger/OpenAPI like minimum, maximum, pattern etc. – but there is no way to specify specific (multilingual) error messages for the validations (Something like “A Username must consist of letters and numbers only” and the translations to multiple languages). Or multiple patterns to be matched (with each another error message tied to it).

  Another method of validation might be an API call on its own (like the check if an email or username is available)

• Relation Metadata For example that the ID field actually referes to the ID of another object (with its own metadata).

Answer 1

The OpenAPI (fka. Swagger) specification can be extended by using x- properties (See Specification Extension is the specification). These x- properties are ignored by standard OpenAPI parsers.

You can define your own properties almost anywhere in the specification file even in JSON schema definitions, but you'll have to write your own parser to use them and/or modify tools such as Swagger UI (which is fairly easy to do) to see them in such tools.

Here's an example with some x-tensions in definitions:

swagger: "2.0"

info:
  version: 1.0.0
  title: X-tension example
  description: Using x- properties to extend the OpenAPI specification
  x-example: we can put x-tension almost anywhere in the specification

paths: {}

definitions:
  User:
    properties:
      id:
        type: string
      name:
        type: string
        maxLength: 50
        minLength: 10
        x-validation:
          multiLingualMessage:
            en: Name's length must be between <minLength> and <maxLength>
            fr: La longeur de Name doit être comprise entre <minLength> et <maxLength>
      friends:
        type: array
        description: An array of UserId
        items:
          type: string
          x-reference:
            type: User

This OpenAPI specification is considered valid by the editor: it ignores the x-properties.

This example is only an illustration of x- properties and do not intend to solve all use cases listed in the question.