Swagger Yaml schema definition for object without a fixed property list

Question

I am implementing an API-first application with the help of Swagger. One of the most important objects to be returned is a DICOM object, which returns a collection of attributes with flexible names, for example:

{ 
  "00080005": {"vr":"CS","Value":["ISO_IR 100"]},
  "00080020": {"vr":"DA","Value":["20160602"]},
  "00080030": {"vr":"TM","Value":["171855.7490"]},
  "00080050": {"vr":"SH","Value":["1234"]},
  "00080090": {"vr":"PN","Value":[{"Alphabetic":"Parikh MD^Anush^M"}]}
}

So I cannot know the name of all the attributes in advance (00080005, 00080030, etc.) although the file structure is very uniform.

My concrete question is: what would be the schema definition for such JSON document.

I have tried the following without success:

definitions:
  DicomMetadataJson:
    type: object
    patternProperties:
      ^\d{8}:
        type: object

but the Swagger Editor returns an error like:

code: "OBJECT_ADDITIONAL_PROPERTIES"

message: "Additional properties not allowed: patternProperties"

description: "A deterministic version of a JSON Schema object."

I have read in the Swagger specification the following, but no example about it: *The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.* — Jaime, Jun 29 '16 at 01:45
exactly the same - it says you can do it but does not show how — danday74, Apr 23 '18 at 15:11

score 6 · Accepted Answer · answered Jun 29 '16 at 08:03

OpenAPI (fka. Swagger) use only a subset of JSON Schema v4 which, unfortunately, do not propose patternProperties.

But given the provided example is a map, you can describe it using additionalProperties:

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap

paths: {}

definitions:
  DicomMetadataJson:
    additionalProperties:
      properties:
        vr:
          type: string
        Value:
          type: array
          items:
            type: string

The key is not defined and is supposed to be a string (therefore you cannot enforce it's format).

Note that SwaggerUI Swagger UI do not render them for now.The issue is tracked here https://github.com/swagger-api/swagger-ui/issues/1248

In the meanwhile you can use this trick define a non required property (default in the example below) of the same type of the map's objects and give some hint within the description:

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap

paths: {}

definitions:
  MetaData:
    properties:
      vr:
        type: string
      Value:
        type: array
        items:
          type: string

  DicomMetadataJson:
    description: 'A <string,MetaData> map, default key is only for documentation purpose'
    properties:
      default:
        $ref: '#/definitions/MetaData'
    additionalProperties:
      $ref: '#/definitions/MetaData'

Concerning the quote The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name., it concerns the format of the OpenAPI specification itself and not the objects used by the API described with an OpenAPI specification.

This is really highly disappointing, as other API languages like RAML does support patterns and in a very concise way. — Jaime, Jun 29 '16 at 08:53
agreed, RAML much better for patterns but offline tooling is lacking :( cant win either way - seems like the area of API definitions is currently in a mess — danday74, Apr 23 '18 at 15:10
@CMCDragonkai It is still true, but patternProperties are implemented in OpenAPI 3.1, which is currently RC1, they call them patterned fields : https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#format — Mickael V., Nov 03 '20 at 19:12

Swagger Yaml schema definition for object without a fixed property list

1 Answers1

Linked