search

json-schema-org / json-schema-spec

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

Extract output to a separate specification #1320

Closed gregsdennis closed 1 year ago

gregsdennis commented 2 years ago

This proposal by @Relequestual (via @jdesrosiers) was originally documented in this discussion.

Moving the output to a separate specification would be advantageous in several ways.

Audience-specific

One of the realizations that came out of @karenetheridge's output format proposal was that there is a difference in needs between output intended to be read by machines vs humans.

What's currently in the spec is intended for machine consumers. Karen's proposal is intended for humans.

We could have separate specifications for each, and implementations could adopt whichever is needed for their intended consumers.

Independent versioning

The current output is versioned along with the Core spec. As such, there were no changes between 2019-09 and 2020-12.

Having the output external to the Core spec allows independent versioning. With the changes coming in draft-next, there will a large burden on implementations to support the new output. This is on top of any changes to schema evaluation. Such a burden can be a deterrent for implementations to support the new schema features.

Having an independent output spec would remove that burden by allowing implementations to support new schema features while still supporting an older output format, and they could separately update the output as they have availability.

Why we maybe shouldn't

@handrews identified that there could be features in JSON Schema (such as annotations) that impose requirements on output. He maintains that such a relationship requires that the output requirements remain in Core.

karenetheridge commented 2 years ago

I support this proposal. The separation will also allow more rapid iteration on the output formats, which can allow for the inclusion of more experimental/optional formats - this area is much more of a "throw things at the wall and see what sticks" than the formality of the rest of the specification.

handrews commented 2 years ago

It's hard to have an opinion on this until the SDLC proposal is resolved.

jdesrosiers commented 2 years ago

It's hard to have an opinion on this until the SDLC proposal is resolved.

That's exactly what I came here to say as well. As mentioned, the main problem right now with the output format being in the spec is versioning, but the proposal introduces a very different versioning system that would change the trade-offs under consideration. I'd have to think about it more, but I think I could still make sense under the new model to have a separately versioned spec for the output system.

Relequestual commented 1 year ago

While I made the following comment on a review of the associated PR, I wanted to share it here, and nudge @karenetheridge to see if, based on the work she has done, it seems feasable...

My thought process was, implementations would then only need to worry about the machine readable version, and then (they or developers) could use external/additional libraries to provide human readable feedback. Not only would this allow for customization, but also for additional languages, or different algorithms to assess such output structures to find the helpful human readable error. - (Original posting)

jdesrosiers commented 1 year ago

@Relequestual I had the same kind of vision for output formats. Ideally there would be only two. One would be a standard way to minimally express pass/fail (FLAG), and another designed solely for machine consumption that would be used by third parties to produce context-appropriate error representations. Ideally, implementations don't need to worry about output beyond the machine readable version, users would just pass it to the third-party output processor that best suits their needs. So far, that has happened, but it would be nice.

That said, I don't think the direction the output work takes is relevant to splitting it into it's own spec document. We can still iterate in whatever direction no matter where it lives.