Ambiguity between JSON string and plain string

[letmaik]

The following is in the 3.1 dev spec:

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }

}

The intention is that the response body contains an arbitrary string, e.g.:

Hello world!

However, this would be invalid given the above JSON schema. A correct response would be:

"Hello world!"

It seems like the spec ignores this inconsistency and somehow implicitly turns JSON schema off in cases where the type is primitive (or just for strings?). The same is true here:

content:
    image/png:
        schema:
            type: string
            contentEncoding: base64

A valid body would be:

"SGVsbG8gd29ybGQh"

But that is again not the intention here.

In summary, I'm missing some language in the spec that describes this behavior explicitly.

Slightly unrelated, there's another example which confuses me:

{
  "description": "user to add to the system",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

Is this supposed to be for example ["Hello", "world!"]? If so, why is the content type text/plain instead of application/json?

[handrews]

@letmaik JSON Schema works on a data model rather than JSON documents.

JSON documents maps trivially to the JSON Schema data model with two exceptions:

• duplicate property names in the same object are not allowed
• numbers are handled mathematically rather than based on their text representation (10, 10.0, 1e1 are all the same value)
  This ensures consistency across different languages and parsers.

Any other document that can be mapped into the JSON data model can also be used with JSON Schema. The JSON Schema spec does not specify how to map other media types to the data model; that is left to the application (in this case, the OpenAPI Specification is the "application").

so

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}

is correct for the text/plain document:

Hello, world!

Or you would use this:

{
  "description": "A simple string response",
  "content": {
    "application/json": {
      "schema": {
        "type": "string"
      }
    }
  }
}

for the application/json document

"Hello, world!"

text/plain trivially maps to a string, and unlike a JSON document consisting of a single string there is no quoting. It's just (literally) plain text.

contentEncoding is used when a different media type, such as image/png, is encoded into a string value. And I'm pretty sure that you caught a bug with the PNG example- thank you! (I'm pretty sure I wrote that one). AFAIK, if you base64 encode anything and send it over HTTP, you would send it as text/plain and rely on the application to do the decoding. That would look like this:

content:
    text/plain:
        schema:
            type: string
            contentMediaType: image/png
            contentEncoding: base64

Note that the Content-Type is text/plain and now there is a contentMediaType: image/png. That means that the HTTP Content-Type header would be text/plain, and it would consist of a bare (not quoted) base64 string that, once decoded, produces a PNG image.

To send a non-encoded PNG file (which is what we'd more often do), you would want:

content:
    image/png:
      schema: {}

I think schema is required, and the empty schema allows everything, including data that does not fit the JSON data model (this has been clarified in the JSON Schema draft after 2019-09, which will go out with OAS 3.1 final). This was clarified specifically to make sure this sort of case in OAS did not conflict with JSON Schema. So here the mapping from image/png into the JSON Schema data model is basically "ignore it". If you were to put a JSON Schema type keyword it would fail because binary image data is not part of the data model. But if you just don't set a type, that's fine.

Keep in mind that this use case is assumed to be there for documentation purposes rather than validation- you could add a "description" to that schema, for example, and it would be fine. But no one is expected to run a binary PNG through a JSON Schema validator.

The other place you would use contentMediaType and possibly contentEncoding has to do with multipart/form-data.

[letmaik]

@handrews Thanks for the detailed explanation. This is very helpful and clears up things. The mapping from content types to the JSON Schema data model is what I would have expected to be part of the spec.

If I understand correctly, then the implicit rules for request bodies and responses are:

• If content type is application/json and a schema is given, then apply the trivial mapping from JSON to JSON Schema data model.
• If content type is application/xml and a schema is given, then map according to ... plus the "xml" object if given.
• If content type is text/plain and a schema is given, then for any schema that is a primitive type, map the content directly to that primitive type. Other non-primitive schemas are undefined for text/plain.

In all cases there is a defined mapping that can be used by validators, and as you said, for text/plain it is likely not often done as there is not much value to it. I think it would be better to spell out the mappings of all supported formats more explicitly though.

The fourth rule would be:

• If the content type is anything else, no mapping to JSON Schema data model is defined.

In those cases it would be up to specific implementations to provide custom mappings if needed, however this would not be generally interoperable.

For other things like operation parameters there are separate mapping rules.

[MikeRalphson]

If I understand correctly, then the implicit rules for request bodies and responses are:

You are missing all JSON and YAML derived media-types from your mapping to the JSON schema JSON object model (e.g. application/problem+json, text/yaml - though that isn't official).

Similarly all xml-derived media-types would use our XML mapping over the JSON object model (e.g. text/xhtml). Thus your fourth rule:

if the content type is anything else, no mapping to JSON Schema data model is defined.

would not apply. I do not see any reason tooling could not implement their own mappings from (say) CBOR, TOML, Protobufs, BSON, MessagePack, so it follows that we would not want to limit the use of such mappings by adding a normative and exhaustive list within the specification.

[handrews]

@letmaik I agree with @MikeRalphson here that there's no need to specify that mappings are undefined, as that discourages people from defining them. The JSON Schema spec handles this, and OAS wouldn't want to discourage people from defining things.

I could see listing out a few more clearly and being a bit more explicit about what's going on since JSON Schema is intentionally vague. OAS has the additional context of being about HTTP APIs, and the use cases are much more concrete.

In particular, a line about how schemas can be used for meta-data even when there is no sensible validation process might be helpful. But I do not feel strongly about this.

I will, however, make a PR to fix that example.

[handrews]

@letmaik I didn't catch this concern:

{
  "description": "user to add to the system",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

can you file that as a separate issue? I have no idea what's going on with it so it won't be in the PR that I'm associating with this issue.