search

json-schema-org / json-hyperschema-spec

A *future* location for the JSON Hyper-Schema I-D sources.
14 stars 4 forks source link

Align hyper-schema output with new standard #3

Open handrews opened 5 years ago

handrews commented 5 years ago

base and links are complex annotations, and the output information should fit in the new output format. So we should explain that. And if it can't be made to fit, we will need to adjust something somewhere.

Relequestual commented 5 years ago

Section 4 of Hyper Schema talks about the output format and examples of output, for the purpose of checking conformance to the specification. https://github.com/json-schema-org/json-schema-spec/blob/9b834f25c206be2669d8f136d573ee40d7c0507b/jsonschema-hyperschema.xml#L288-L328

It looks like the HyperSchema tests didn't get off the ground: https://github.com/json-schema-org/JSON-Schema-Test-Suite/issues/203

I'm not clear what this issue is looking to achive.

If I understand correctly, a hypermedia engine which implemented JSON Hyper Schema, should output some JSON based on instance and schema, allowing a UI to be constructed to allow hypermedia navigation, based on the applicability of keyords to the instance.

Given this, I'm not sure if trying to find any alignment in the validation and hypermedia output JSON makes sense. It feels a bit like Apples and Oranges in terms of the purpose of the output format.

I spent the last hour reading this issue and the hyperschema document, and my feeling is there's something you (@handrews) had in mind for this that isn't documented here (which is to be expected because you had likely planned to resolve this issue yourself).

My inclination is to not spend any more time on this myself, leaving it to someone who is more likely to understand the intent, and cover all the other issues first, which may leave enough time for someone to come back to this during the 1 month review process.

handrews commented 5 years ago

@Relequestual the links keyword is effectively a very complex annotation, the value of which depends in part on the instance (unlike simple annotations such as readOnly, the value of which is given directly in the schema).

That output format was given because there was no output specification at all. But it's trying to do similar things to what the annotation output format is doing. So I kind of assumed we should put it into that format (despite not really having a good intuitive feel for that as I have only followed the output discussions at a very high level, and the hyper-schema output was done so long ago I've forgotten the details).

However, if you think it is better to leave it separate for now I have no problem with that. Anything to get the specs out the door sooner is good with me- if folks want to, this can be merged with the other output rules in the next draft.

Relequestual commented 5 years ago

I'm going to migrate this out of the draft-8 milestone.