For response body with Content-Type=text/plain, "style" and "explode" are undefined

[kerrykimbrough]

For a response body with Content-Type=text/plain, "style" and "explode" ought to apply. Different API implementations might need to make different choices for how these data values are serialized. But there is no mention of this in the spec.

Shouldn't the spec prescribe optional "style" and "explode" fields for a Media Type Object (similar to those in an Encoding Object)? If not, shouldn't the spec explain the default values that should be assumed?

[kerrykimbrough]

Sorry, my original description was a bit confused and I have corrected it. But this issue applies as well to a text/plain request body.

I do see that it's incongruous for a general Media Type Object to address concerns for a specific media type. So I'm not sure how best to resolve the serialization ambiguity for text/plain.

[karenetheridge]

For a response body with Content-Type=text/plain, "style" and "explode" ought to apply.

FWIW I don't see how media types can play along with "style" and "explode" at all. Using these keywords makes sense for parameters that don't have a media-type encoding at all, but surely all of the encoding/decoding would be indicated by the media type and there is no need for more. So for request/response bodies, which must always have a media type, it doesn't make sense at all.

It would be nice to have some examples showing how these keywords can play together, or otherwise amend the specification to remove the use of style/explode for bodies entirely, and state that either a parameter has a media type, OR it uses style/explode, but not both.

[kerrykimbrough]

Consider the example below. PUT /object sends and receives an object encoded as a text string. But how are API server and client expected to decode these strings? The media type text/plain certainly offers no information.

In other situations, the API definition can specify an encoding using style and explode (for parameters and headers and even for request body/response, in the case of content.application/x-www-form-urlencoded.encoding).

But in this situation? Bupkis.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Text",
    "version": "0.0.0"
  },
  "paths": {
    "/object": {
      "put": {
        "requestBody": {
          "content": {
            "text/plain": {
              "schema": {
                "type": "object",
                "properties": {
                  "A": {
                    "type": "string"
                  },
                  "B": {
                    "type": "number"
                  },
                  "C": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "A": {
                      "type": "string"
                    },
                    "B": {
                      "type": "number"
                    },
                    "C": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Failure",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}

[kerrykimbrough]

Another approach might be to register a new media type: text/openapi;style=string;explode=boolean

[webron]

text/plain by definition is just a string of text. It offers no serialization information and the schema is pretty much meaningless for it. Our schemas are based on JSON Schema and they pretty much can only be used to describe JSON (and some level of YAML) structures. Originally we added some level of support to representing XML using it, but it's limited and I wouldn't recommend anyone to use it.

It's unlikely we'll get into the business of describing how to serialize non-standard structures. If you want to use a structured request/response - use JSON. If you want to use a different serialized form - you can use an extension to reference it (for example, use XSD). If you're just using plain text - then that's what it is, plain text, not structured data.

For what it's worth, we did have a proposal in the past to add support for additional (standard) serialization methods, but we didn't get enough traction to actually have those end up in the spec. That would have not really helped your use case because it seems what you're trying to do is non-standard.

[kerrykimbrough]

I wouldn't say the situation described this issue is non-standard, although it is probably atypical. This issue didn't arrive out of an actual API use case. I came to it while building testing tools that use an OpenAPI definition to decode and validate API response data.

If we assume that text/plain can never be used to exchange structured data, then this issue would describe a situation in which the response schema simply can't be validated. In which case, I agree this issue can be withdrawn.

[webron]

I didn't say the situation is non-standard, said you're using a non-standard method of describing serialization. JSON can also be sent using text/plain, but trying to describe it as JSON without saying it's JSON would be a nightmare. If one wants to send structured data, the best way would be to use one of the (many) serialization standards out there, that are probably going to have a media type to describe them already (whether they have a modeling/validation language that can be used for validation is outside of our scope). Beyond that, I wouldn't bother with validating text/plain other than maybe... that it's text.

[karenetheridge]

If we assume that text/plain can never be used to exchange structured data, then this issue would describe a situation in which the response schema simply can't be validated.

That would be my interpretation. text/plain content only produces strings, so the only valid type that you can expect to get when evaluating the schema is "string".

Maybe you could argue that if the schema says {"type":"number"} and the response body is all digits, then the value provided to the schema should be interpreted as a number, to make it easier to perform validations like {"minimum": 10} or similar. I've certainly wanted to treat some query or header values as numbers so I can perform range checks on them.

[handrews]

text/plain is what you use when you either have literal plain text, or you are serializing to a text format for which there is no media type and therefore no standardized mechanism that is possible.

I've added some basic guidance in PR #3840, which mostly just confirms that you're on your own, but that's as far as I think we can go.