JRI from an AsyncAPI perspective

Open
#17 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
json
Domain
documentation

Research direction

Start with draft-handrews-jri.md, especially the sections on extending JRI, standalone implementations, avoiding behavioral overlap, fragments and secondary resources, and serving. Compare the stated JRI behavior with the AsyncAPI perspective and document a resolved position on the four questions; the issue is done when the specification guidance is clear and agreed.

Written by the indexing model from the issue text.

Description

@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.

Dominant language
Makefile
Stars
9
Forks
1
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from json-schema-org/referencing

All issues in json-schema-org/referencing

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.