search

json-schema-org / referencing

Proposals for a possible specification encompassing the varying uses of "$ref"
MIT License
6 stars 1 forks source link

JRI from an AsyncAPI perspective #17

Open jonaslagoni opened 1 year ago

jonaslagoni commented 1 year ago

@handrews do correct me if I am wrong in any of the cases 😆

  1. Should always produce a valid JSON document (resolving referenced resource should always be compatible with JSON)

Defined by https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#general-syntax

  1. Should define the behavior for referencing non-JSON resources in a JSON document (this can be as simple as resolving the content into a string value)
  2. Should define the behavior for referencing JSON data

Same as JRef, this is decided per media type, and explicitly allow the context specification to determine the behavior, any of the above use-cases seem to be covered.

  1. Should define the behavior for referencing JSON data that also have reference behavior, and how they interconnect / or not (say two standards both use $ref the new standard should define a clear separation between the two and how referencing tools should interpret it)

https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#extending-jri-extending https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#standalone-jri-implementations https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#avoiding-behavioral-overlap

Everything is context aware, and is dynamic based on media type, i.e. resolving references in a JSON Schema context follows different rules for $ref then in the context specification of JRI.

  1. Should define the behavior of nested schemas within the same file (so there is no difference between what the spec allows and what tooling enables)

https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#fragments-and-secondary-resources defines the behavior for fragments and secondary resources.

https://github.com/json-schema-org/referencing/blob/main/draft-handrews-jri.md#discovering-caching-and-serving-resources-serving defines the behavior for caching and bundling.

Context specifications take priority, which clears up the confusion.

handrews commented 1 year ago

Thanks, @jonaslagoni - let's start with:

Should always produce a valid JSON document (resolving referenced resource should always be compatible with JSON)

I assume "produce" here means removing all references and replacing them with their targets in some way. This is not possible with cyclic references. Are you just trying to remove all of the non-JSON Schema references because they are guaranteed to not be cyclic?

What exactly is driving the need to produce a valid JSON document (which can then be parsed and loaded into memory like any other JSON document) vs being able to load the original document(s) into a usable in-memory representation mixing JSON and non-JSON values in a way that is clear while traversing the data-structure?

If you resolve non-JSON reference targets to a string that is embedded into a JSON file, then when you parse that JSON file you will need to know that the string in that spot requires further parsing and interpretation. So with either approach, you need to know when and how to handle that bit of in-memory data.

This feels a bit to me like a tension between "$ref"'s late-binding design (which is necessary for cyclic reference support among other things) and some other requirement I don't quite understand.

jonaslagoni commented 1 year ago

I assume "produce" here means removing all references and replacing them with their targets in some way

It was to emphasize that the referencing standard takes it's root in JSON (cause that's what you write the AsyncAPI file in), so naturally the referencing standard (as JSON Reference) should work within that restriction, even though you might reference something that is not.

Are you just trying to remove all of the non-JSON Schema references because they are guaranteed to not be cyclic?

Nothing is guaranteed, while something like protobuf does not support circular types, XSD does.

What exactly is driving the need to produce a valid JSON document (which can then be parsed and loaded into memory like any other JSON document) vs being able to load the original document(s) into a usable in-memory representation mixing JSON and non-JSON values in a way that is clear while traversing the data-structure?

It comes from an implementation point of view, and specifically these two cases come to mind:

  1. Without a JSON structure, how will you apply fragments? Cause if it's not clear what is arrays and what is objects fragments might be mismatching what is intended (if fragments are allowed of course)
  2. We need a way to interact with the referenced resource, to be able to use it in tooling. Here the easiest IMO was just to keep it JSON 🙂