✨ Proposal: Provide resourceMediaType and resourceSchema when string format is a resource identifier, similar to contentMediaType and contentSchema

[torsknod-the-caridian]

Describe the inspiration for your proposal

I have JSON schemata, which contain URIs to further data (mostly further JSON and/ or XML, sometimes ZIPed before).
It would be helpful to have a way to define in which format this data, so people know what they can and have to support when following the data.

Describe the proposal

We already have https://json-schema.org/understanding-json-schema/reference/non_json_data#contentmediatype and https://json-schema.org/understanding-json-schema/reference/non_json_data#contentschema .
If the type is string and format is one of https://json-schema.org/understanding-json-schema/reference/string#resource-identifiers, allow to provide resourceMediaType and resourceSchema following the same rules like contentMediaType and contentSchema.

Describe alternatives you've considered

I first thought about using contentMediaType and contentSchema, but this is meant for the content to be the string, not the string being the reference to it.
This might cause trouble with existing tooling.

Additional context

No response

[gregsdennis]

Thanks for the proposal. It sounds like you're suggesting that we provide the media type of a secondary resource that they'd need to fetch (e.g. from another server). If that's the case,

1. The server should return the correct media type for the content its serving. Any indication of the media type in the schema would be at best redundant and at worst wrong.
2. We discourage implementations from automatically fetching external resources (even schemas through $ref) for various reasons, including some security concerns. It seems you're suggesting this would be a user/client action rather than the implementation, but it's still something to be aware of.

If the schema implementation itself isn't supposed to do anything with these hints, I recommend just adding an annotation keyword. In 2020-12, you can use any keyword, and it will be ignored by the implementation; moving forward, you'll need to prefix the keyword with x- to get the same effect. (The content* keywords are all annotations as well.)

[jdesrosiers]

It's a little unclear from your description, but it sounds like what you're looking for is JSON Hyper-Schema. Specifically, you're looking for targetMediaType and targetSchema. As Greg, pointed out, the HTTP response is the authority of the actual media type and schema and these keywords are just hints, but hints can be useful sometimes.

We're working on some friendly getting-started type documentation for JSON Hyper-Schema, but for now all we have is the specification which can be a bit dense. If you want to provide a simple example of the kind of thing you're doing, I'd be happy to show how you could express it using JSON Hyper-Schema.

[torsknod-the-caridian]

Seems I did not send my comment. :-(
@gregsdennis Basically yes, the thing is that when you provide a schema to someone, they do not necessarily know the data to-be confirming to the schema and especially not the data which will get referenced by URIs.
However, the software they are developing (or validating) has to support the media/ mime types of the data referenced by the URIs.
They also have to support the respective URL schemata, crypto algorithms and so on.
Because of that I would be helpful to reference what is to be expected from the resource at the URI.

@jdesrosiers I try to simplify an example. I had to take this completely out of context to be able to write this in public.
Let's say this is my data subset.

{
  "DetailDataReferenced": "https://bla.blub/resource.whatever"
}

My JSON schema would be something like:

{
  "type": "object",
  "properties": {
    "DetailDataReferenced": {
      "type": "string",
      "format": "uri"
    }
  }
}

This for sure tells me that this string is an URI (well in fact even an URL in my case), but not which media/ mime type to expect from the other side, which I have to support in my software.

What we would need is something like:

{
  "type": "object",
  "properties": {
    "DetailDataReferenced": {
      "type": "string",
      "format": "uri",
      "contentType": "application/json; profile=urn://my.own.schema"
    }
  }
}

I used profile here, because I saw in https://datatracker.ietf.org/doc/html/rfc6906, which mentions XML as an example.
When combining this with anyOf a set of (to be) supported schemata can be defined.
However, this "only" covers the content type, nothing more like URL scheme's, to be supported chipher suites and so on.
Also it only covers getting, not other operations of REST interface or even things not using HTTP.
At least for REST/ API we would some way to define something like https://spec.openapis.org/oas/v3.1.0#operation-object.
OpenAPI itself would not work, because this is requring to specify the URL.

Hope this helps for explanation.

[jdesrosiers]

Here's the example using JSON Hyper-Schema to describe following the URI as a link.

{
  "type": "object",
  "properties": {
    "DetailDataReferenced": {
      "type": "string",
      "format": "uri",
      "links": [
        {
          "rel": "https://example.com/relations/detail-data",
          "href": "{+detailUrl}",
          "templatePointers": {
            "detailUrl": "0"
          },
          "targetMediaType": "application/json",
          "targetSchema": { "$ref": "urn:my-namespace:my.own.schema" }
        }
      ]
    }
  }
}

Note that profile isn't a valid parameter for application/json. Each media type needs to opt-in to using profile and JSON hasn't. However, I think what you're trying to express is a schema that describes the response. You can do that with the targetSchema keyword.

Also note that urn://my.own.schema isn't a valid URN. I strongly suggest using something else. URNs have the form urn:<namespace-identifier>:<namespace-specific-string> where the NID must be registered. Unless you're using the uuid namespace, URN's are pretty useless. Consider using the tag: scheme instead: tag:example.com,2025:my.own.schema.

it only covers getting, not other operations of REST interface or even things not using HTTP.

You can express that too with JSON Hyper-Schema. Here's the spec to learn more, https://json-schema.org/draft/2019-09/draft-handrews-json-schema-hyperschema-02