search

json-schema-org / json-schema-spec

The JSON Schema specification
http://json-schema.org/
Other
3.42k stars 251 forks source link

jsonschema: declarative language or media type? #1185

Open ioggstream opened 2 years ago

ioggstream commented 2 years ago

I wish

to clarify whether json schema is a declarative language or

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

https://github.com/json-schema-org/json-schema-spec/blob/707431358d529dc8892610e4d8593cfdd1f090a3/jsonschema-core.xml#L63

note

This may be not trivial ;)

Relequestual commented 2 years ago

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

awwright commented 2 years ago

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

ioggstream commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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.