addition of positional schema, encoding for media type object

Author: mattpolzin

Sources/OpenAPIKit/Content/Content.swift

@@ -12,10 +12,31 @@ extension OpenAPI {
     /// 
     /// See [OpenAPI Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object).
     public struct Content: Equatable, CodableVendorExtendable, Sendable {
+        /// A schema describing the complete content of the request, response,
+        /// parameter, or header.
         public var schema: JSONSchema?
+
+        /// A schema describing each item within a sequential media type.
+        public var itemSchema: JSONSchema?
+
         public var example: AnyCodable?
         public var examples: Example.Map?
-        public var encoding: OrderedDictionary<String, Encoding>?
+
+        /// Provide either a map of encodings or some combination of prefix-
+        /// and item- positional encodings.
+        ///
+        /// If the OpenAPI Document specifies the 'encoding' key (a map)
+        /// then this property will be set to its first case. If the OpenAPI
+        /// Document specifies either or both of the 'prefixEncoding' and
+        /// 'itemEncoding' keys, this property will be set to its second case.
+        ///
+        /// You can access the encoding map (OAS 'encoding' property) as the `Content`
+        /// type's `encodingMap` as well.
+        ///
+        /// You can access the positional encoding (OAS 'prefixEncoding' and
+        /// `itemEncoding` properties) as the `Content` type's `prefixEncoding`
+        /// and `itemEncoding` properties.
+        public var encoding: Either<OrderedDictionary<String, Encoding>, PositionalEncoding>?
 
         /// Dictionary of vendor extensions.
         ///
@@ -24,18 +45,87 @@ extension OpenAPI {
         /// where the values are anything codable.
         public var vendorExtensions: [String: AnyCodable]
 
+        /// The encoding of this `Content` (Media Type Object) if it is a map
+        /// from property names to encoding information.
+        ///
+        /// This property gets modified as part of the `encoding` property.
+        ///
+        /// See also the `prefixEncoding` and `itemEncoding` properties.
+        public var encodingMap: OrderedDictionary<String, Encoding>? { encoding?.a }
+
+        /// The positional prefix-encoding for this `Content` (Media Type
+        /// Object) if set.
+        ///
+        /// This property gets modified as part of the `encoding` property.
+        ///
+        /// See also the `itemEncoding` and `encodingMap` properties.
+        public var prefixEncoding: [Encoding]? { encoding?.b?.prefixEncoding }
+
+        /// The positional item-encoding for this `Content` (Media Type
+        /// Object) if set.
+        ///
+        /// This property gets modified as part of the `encoding` property.
+        ///
+        /// See also the `prefixEncoding` and `encodingMap` properties.
+        public var itemEncoding: Encoding? { encoding?.b?.itemEncoding }
+
         /// Create `Content` with a schema, a reference to a schema, or no
         /// schema at all and optionally provide a single example.
         public init(
             schema: JSONSchema?,
+            itemSchema: JSONSchema? = nil,
             example: AnyCodable? = nil,
             encoding: OrderedDictionary<String, Encoding>? = nil,
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.schema = schema
+            self.itemSchema = itemSchema
+            self.example = example
+            self.examples = nil
+            self.encoding = encoding.map(Either.a)
+            self.vendorExtensions = vendorExtensions
+        }
+
+        /// Create `Content` with a schema, a reference to a schema, or no
+        /// schema at all and optionally provide a single example.
+        public init(
+            schema: JSONSchema?,
+            itemSchema: JSONSchema? = nil,
+            example: AnyCodable? = nil,
+            prefixEncoding: [Encoding] = [],
+            itemEncoding: Encoding? = nil,
+            vendorExtensions: [String: AnyCodable] = [:]
+        ) {
+            self.schema = schema
+            self.itemSchema = itemSchema
+            self.example = example
+            self.examples = nil
+            if itemEncoding != nil || prefixEncoding != [] {
+                self.encoding = .b(.init(prefixEncoding: prefixEncoding, itemEncoding: itemEncoding))
+            } else {
+                self.encoding = nil
+            }
+            self.vendorExtensions = vendorExtensions
+        }
+
+        /// Create `Content` with a schema, a reference to a schema, or no
+        /// schema at all and optionally provide a single example.
+        public init(
+            itemSchema: JSONSchema?,
+            example: AnyCodable? = nil,
+            prefixEncoding: [Encoding] = [],
+            itemEncoding: Encoding? = nil,
+            vendorExtensions: [String: AnyCodable] = [:]
+        ) {
+            self.schema = nil
+            self.itemSchema = itemSchema
             self.example = example
             self.examples = nil
-            self.encoding = encoding
+            if itemEncoding != nil || prefixEncoding != [] {
+                self.encoding = .b(.init(prefixEncoding: prefixEncoding, itemEncoding: itemEncoding))
+            } else {
+                self.encoding = nil
+            }
             self.vendorExtensions = vendorExtensions
         }
 
@@ -50,22 +140,24 @@ extension OpenAPI {
             self.schema = .reference(schemaReference.jsonReference, description: schemaReference.description)
             self.example = example
             self.examples = nil
-            self.encoding = encoding
+            self.encoding = encoding.map(Either.a)
             self.vendorExtensions = vendorExtensions
         }
 
         /// Create `Content` with a schema and optionally provide a single
         /// example.
         public init(
             schema: JSONSchema,
+            itemSchema: JSONSchema? = nil,
             example: AnyCodable? = nil,
             encoding: OrderedDictionary<String, Encoding>? = nil,
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.schema = schema
+            self.itemSchema = itemSchema
             self.example = example
             self.examples = nil
-            self.encoding = encoding
+            self.encoding = encoding.map(Either.a)
             self.vendorExtensions = vendorExtensions
         }
 
@@ -89,7 +181,7 @@ extension OpenAPI {
             }
             self.examples = examples
             self.example = examples.flatMap(Self.firstExample(from:))
-            self.encoding = encoding
+            self.encoding = encoding.map(Either.a)
             self.vendorExtensions = vendorExtensions
         }
 
@@ -104,22 +196,61 @@ extension OpenAPI {
             self.schema = .reference(schemaReference.jsonReference)
             self.examples = examples
             self.example = examples.flatMap(Self.firstExample(from:))
-            self.encoding = encoding
+            self.encoding = encoding.map(Either.a)
             self.vendorExtensions = vendorExtensions
         }
 
         /// Create `Content` with a schema and optionally provide a map
         /// of examples.
         public init(
             schema: JSONSchema,
+            itemSchema: JSONSchema? = nil,
             examples: Example.Map?,
             encoding: OrderedDictionary<String, Encoding>? = nil,
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.schema = schema
+            self.itemSchema = itemSchema
+            self.examples = examples
+            self.example = examples.flatMap(Self.firstExample(from:))
+            self.encoding = encoding.map(Either.a)
+            self.vendorExtensions = vendorExtensions
+        }
+
+        /// Create `Content` with a schema and optionally provide a map
+        /// of examples.
+        public init(
+            itemSchema: JSONSchema?,
+            examples: Example.Map?,
+            encoding: OrderedDictionary<String, Encoding>? = nil,
+            vendorExtensions: [String: AnyCodable] = [:]
+        ) {
+            self.schema = nil
+            self.itemSchema = itemSchema
+            self.examples = examples
+            self.example = examples.flatMap(Self.firstExample(from:))
+            self.encoding = encoding.map(Either.a)
+            self.vendorExtensions = vendorExtensions
+        }
+
+        /// Create `Content` with a schema and optionally provide a map
+        /// of examples.
+        public init(
+            itemSchema: JSONSchema? = nil,
+            examples: Example.Map?,
+            prefixEncoding: [Encoding] = [],
+            itemEncoding: Encoding? = nil,
+            vendorExtensions: [String: AnyCodable] = [:]
+        ) {
+            self.schema = nil
+            self.itemSchema = itemSchema
             self.examples = examples
             self.example = examples.flatMap(Self.firstExample(from:))
-            self.encoding = encoding
+            if itemEncoding != nil || prefixEncoding != [] {
+                self.encoding = .b(.init(prefixEncoding: prefixEncoding, itemEncoding: itemEncoding))
+            } else {
+                self.encoding = nil
+            }
             self.vendorExtensions = vendorExtensions
         }
     }
@@ -159,6 +290,7 @@ extension OpenAPI.Content: Encodable {
         var container = encoder.container(keyedBy: CodingKeys.self)
 
         try container.encodeIfPresent(schema, forKey: .schema)
+        try container.encodeIfPresent(itemSchema, forKey: .itemSchema)
 
         // only encode `examples` if non-nil,
         // otherwise encode `example` if non-nil
@@ -168,7 +300,18 @@ extension OpenAPI.Content: Encodable {
             try container.encode(example, forKey: .example)
         }
 
-        try container.encodeIfPresent(encoding, forKey: .encoding)
+        if let encoding {
+            switch encoding {
+            case .a(let encoding):
+                try container.encode(encoding, forKey: .encoding)
+
+            case .b(let positionalEncoding):
+                if !positionalEncoding.prefixEncoding.isEmpty {
+                    try container.encode(positionalEncoding.prefixEncoding, forKey: .prefixEncoding)
+                }
+                try container.encodeIfPresent(positionalEncoding.itemEncoding, forKey: .itemEncoding)
+            }
+        }
 
         if VendorExtensionsConfiguration.isEnabled(for: encoder) {
             try encodeExtensions(to: &container)
@@ -188,9 +331,27 @@ extension OpenAPI.Content: Decodable {
             )
         }
 
+        guard !(container.contains(.encoding) && (container.contains(.prefixEncoding) || container.contains(.itemEncoding))) else {
+            throw GenericError(
+                subjectName: "Encoding and Positional Encoding",
+                details: "If `prefixEncoding` or `itemEncoding` are specified then `encoding` is not allowed in the Media Type Object (`OpenAPI.Content`).",
+                codingPath: container.codingPath
+            )
+        }
+
         schema = try container.decodeIfPresent(JSONSchema.self, forKey: .schema)
+        itemSchema = try container.decodeIfPresent(JSONSchema.self, forKey: .itemSchema)
+
+        if container.contains(.encoding) {
+            encoding = .a(try container.decode(OrderedDictionary<String, Encoding>.self, forKey: .encoding))
+        } else if container.contains(.prefixEncoding) || container.contains(.itemEncoding) {
+            let prefixEncoding = try container.decodeIfPresent([Encoding].self, forKey: .prefixEncoding) ?? []
+            let itemEncoding = try container.decodeIfPresent(Encoding.self, forKey: .itemEncoding)
 
-        encoding = try container.decodeIfPresent(OrderedDictionary<String, Encoding>.self, forKey: .encoding)
+            encoding = .b(.init(prefixEncoding: prefixEncoding, itemEncoding: itemEncoding))
+        } else {
+            encoding = nil
+        }
 
         if container.contains(.example) {
             example = try container.decode(AnyCodable.self, forKey: .example)
@@ -208,13 +369,24 @@ extension OpenAPI.Content: Decodable {
 extension OpenAPI.Content {
     internal enum CodingKeys: ExtendableCodingKey {
         case schema
+        case itemSchema
         case example  // `example` and `examples` are mutually exclusive
         case examples // `example` and `examples` are mutually exclusive
         case encoding
+        case itemEncoding
+        case prefixEncoding
         case extended(String)
 
         static var allBuiltinKeys: [CodingKeys] {
-            return [.schema, .example, .examples, .encoding]
+            return [
+                .schema,
+                .itemSchema,
+                .example,
+                .examples,
+                .encoding,
+                .itemEncoding,
+                .prefixEncoding
+            ]
         }
 
         static func extendedKey(for value: String) -> CodingKeys {
@@ -225,12 +397,18 @@ extension OpenAPI.Content {
             switch stringValue {
             case "schema":
                 self = .schema
+            case "itemSchema":
+                self = .itemSchema
             case "example":
                 self = .example
             case "examples":
                 self = .examples
             case "encoding":
                 self = .encoding
+            case "itemEncoding":
+                self = .itemEncoding
+            case "prefixEncoding":
+                self = .prefixEncoding
             default:
                 self = .extendedKey(for: stringValue)
             }
@@ -240,12 +418,18 @@ extension OpenAPI.Content {
             switch self {
             case .schema:
                 return "schema"
+            case .itemSchema:
+                return "itemSchema"
             case .example:
                 return "example"
             case .examples:
                 return "examples"
             case .encoding:
                 return "encoding"
+            case .itemEncoding:
+                return "itemEncoding"
+            case .prefixEncoding:
+                return "prefixEncoding"
             case .extended(let key):
                 return key
             }

Sources/OpenAPIKit/Content/ContentPositionalEncoding.swift

@@ -0,0 +1,41 @@
+//
+//  ContentPositionalEncoding.swift
+//
+//
+//  Created by Mathew Polzin on 12/29/19.
+//
+
+import OpenAPIKitCore
+
+extension OpenAPI.Content {
+    /// OpenAPI Spec `itemEncoding` and `prefixEncoding` on the "Media Type Object"
+    ///
+    /// See [OpenAPI Media Type Object](https://spec.openapis.org/oas/v3.2.0.html#media-type-object).
+    public struct PositionalEncoding: Equatable, Sendable {
+
+        /// An array of positional encoding information, as defined under
+        /// [Encoding By Position](https://spec.openapis.org/oas/v3.2.0.html#encoding-by-position).
+        /// The `prefixEncoding` field **SHALL** only apply when the media type is
+        /// `multipart`. If no Encoding Object is provided for a property, the
+        /// behavior is determined by the default values documented for the
+        /// Encoding Object.
+        public var prefixEncoding: [OpenAPI.Content.Encoding]
+
+        /// A single Encoding Object that provides encoding information for
+        /// multiple array items, as defined under [Encoding By Position](https://spec.openapis.org/oas/v3.2.0.html#encoding-by-position).
+        /// The `itemEncoding` field **SHALL** only apply when the media type
+        /// is multipart. If no Encoding Object is provided for a property, the
+        /// behavior is determined by the default values documented for the
+        /// Encoding Object.
+        public var itemEncoding: OpenAPI.Content.Encoding?
+
+        public init(
+            prefixEncoding: [OpenAPI.Content.Encoding] = [],
+            itemEncoding: OpenAPI.Content.Encoding? = nil
+        ) {
+            self.prefixEncoding = prefixEncoding
+            self.itemEncoding = itemEncoding
+        }
+    }
+}
+