jsonschema: declarative language or media type?

[ioggstream]

I wish

to clarify whether json schema is a declarative language or

a JSON-based format for describing the structure of JSON data

json-schema-spec/jsonschema-core.xml

Line 63 in 7074313

JSON Schema defines the media type "application/schema+json", a JSON-based format

note

This may be not trivial ;)

[Relequestual]

Why not both?
The details of what JSON Schema IS, depends on who I'm talking to.

[awwright]

Any "format for describing the structure of (other) data" sounds like a type of declarative language. Is your understanding different?

[ioggstream]

When I first read the spec, I found that defining json schema as a media type was confusing, since iiuc a media type is a "label" for some content.

Stating that it's either a "declarative language" or a "format for describing the structure" is probably more clear to a first-time reader. I think the definition provided by @jdesrosiers here, is a perfect fit for an Abstract/Introduction.

https://github.com/ietf-wg-httpapi/mediatypes/blame/main/draft-ietf-httpapi-rest-api-mediatypes.md#L319

[jdesrosiers]

This is definitely confusing, because there is JSON Schema the language and JSON Schema the media type. They are two distinct things, but have the same name.

JSON Schema the media type is the JSON media type with a few extensions including fragment identification, a media type parameter, and $schema. That's all it is. In theory, someone could use this media type for something that has nothing to do with JSON Schema the language.

JSON Schema the language is everything else including the keywords, references, and any other design decisions.

At least that's how I see it.

When the media type is registered, we can remove all the media type stuff from the JSON Schema spec for the next release. When we're doing that, we can make things more clear since we only have to define the language and not the media type.

[awwright]

They are two distinct things, but have the same name.

When I say JSON Schema is a media type, among the other components of its media type registration (the application/schema+json name, fragment semantics, etc), there's the complete specification of its semantics. You can't really talk about a media type without talking about how a computer program processes it, in the normative.

And when I talk about media types in general, there's a large variety of them— images, data, scripting languages, executable code, or a combination of these. Of these, I would call JSON Schema a declarative, JSON-based vocabulary.

[gregsdennis]

I think there's a distinction here that should be made. There are two parts at work here:

1. a declarative language which allows multiple functions, including validation of data that is structured according to the JSON data model
2. a media type which indicates that a given media should be processed as (1)

Perhaps the solution is to not mention the media type in the specification and declare the media type separately via a registration.

[gregsdennis]

Reviewing this again, and comparing with RFC9535 for an example of how to go about this. It looks like section 6 declares a registration. Then, looking at the IANA registration page, it appears the application/jsonpath registration carries a link to RFC9535.

I can only assume that they published the spec, including the section about the registration, then registered application/jsonpath with IANA.

@jdesrosiers has mentioned in the past a difficulty for us in that we are an ever-evolving specification, with multiple "live" versions, some of which conflict with each other. Specifying application/schema+json alone may not be sufficient to describe the rules with which the content should be interpreted. His solution was something akin to having a version parameter that identified which version of JSON Schema to use.

I think that removing mentions of the media types from the specification isn't the right move. We do have an "IANA Considerations" section which defines application/schema+json and application/schema-instance+json. With this upcoming release, we will have a definite version number that can be used as a parameter. It seems that this is the approach we need to take.

Then, once we have released, we need to actually register the media types with IANA, which may have its own complications.

[jdesrosiers]

@gregsdennis Have a look at the YAML registration as an example of registering a media type for self-published spec. That's a better parallel for us than JSON Path.

His solution was something akin to having a version parameter that identified which version of JSON Schema to use.

That's not quite what I meant. The version parameter (originally profile, then schema), is really just an alternative to $schema. I don't think we can use that to define the media type registration. Splitting the registration between the registration RFC and an arbitrary second source sounds like a complicated mess even if it does turn out to be an approach IETF/IANA finds acceptable. I think the registration needs to be defined in one place.

The solution I proposed was to define the media type in the registration in a way that is backwards compatible with all previous versions.

I've also proposed the possibility of simply ignoring any compatibility concerns from the previous draft releases and just worry about defining something for the stable release forward.

I think that removing mentions of the media types from the specification isn't the right move.

I still think it's best to decouple the registration from an particular version of the spec. Even if we take my second suggestion and only worry about the stable version, there's still a possibility that we need to make a breaking change and there's a new stable version. Then we would need to update the registration to point to the new spec even if the registration doesn't need to change.