JRef from an AsyncAPI perspective

[jdesrosiers]

This is a response to #14. By request, I'm responding here so we can fork the discussion for JRef specific discussion.

---

Here's how I see that JRef applies to your requirements for AsyncAPI. I hope it's helpful.

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

In JRef, references are always transparent. Developers are always working only with the standard JSON types. When you get a value from a JRef document, the JRef tooling follows the reference automatically and gives you the referenced value as if the referenced value was always there.

Example

const doc = JRef.load({
  "foo": { "$href": "#/bar" },
  "bar": "42"
});

const foo = JRef.get("/foo", doc); // => 42
const bar = JRef.get("/bar", doc); // => 42

2. 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)

JRef allows implementations to define how they want non-JSON values to be represented. Everything is based on media types. You can have XML converted into a JRef compatible document, or just return it as a string. You would write a plugin for the JRef tooling describing the behavior you expect for each media type.

Example:

const doc = JRef.load({
  "schema": { "$href": "./my-xml-schema.xml" }
});

const xmlSchema = JRef.get("/schema", doc); // => Some representation of an XML document
const value = XML.get(someXPathExpression, xmlSchema); // => The value of applying the XPath expression to the XML document

3. Should define the behavior for referencing JSON data

The JRef proposal covers the behavior of references in JRef documents. Although JRef is syntactically compatible with JSON, it's considered a different media type and must be configured as a plugin the same way you would for XML.

Example

const doc = JRef.load({
  "foo": { "$href": "./my-json-document.json" }
});

// ./my-json-document.json
// {
//    "aaa": { "$href": "#/bbb" },
//    "bbb": 42
// }

const foo = JRef.get("/foo", doc);
const aaa = foo.aaa; // => { "$href": "#/bbb" } # A value that looks like a JRef reference, but is actually just a plain JSON object with no special meaning
const bar = foo.bbb; // => 42

4. 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)

Every document has a media type and each media type has it's own rules for referencing. If you reference a JSON Schema from a JRef document, once you follow that reference, then only the rules for JSON Schema apply. Because it's document based, there are some consequences to be aware of. If your AsyncAPI document identifies as a JRef media type, you can't embed a JSON Schema in that document because it's a different media type. You can only reference to a JSON Schema. That shouldn't be a big deal because it's what you already have to do for non-JSON compatible types already.

One way around that is to define AsyncAPI as a separate media type that defines that certain locations are to be interpreted as JSON Schemas. Then it can be a reference or inline. But, that would require extra work to extend the standard JRef tooling.

Another way around that is to introduce some syntax for embedding external documents in a JRef document. I've explained why an embedding/bundling feature is not included in #7, but I'm open to discussion if there's demand for it.

If both AsyncAPI and JSON Schema decide to adopt JRef, this problem goes away, but I don't think that's likely from the JSON Schema side.

5. 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)

JRef doesn't restrict where a reference can be or what can be referenced. Because the tooling abstracts away references, there should be no developer burden and AsyncAPI document authors are empowered to use references however fits their needs. If AsyncAPI does want to make restrictions like this, they would need to define their own media type and would have to extend the standard tooling.

[gregsdennis]

You can have XML converted into a JRef compatible document

Is this conversion defined by JRef, or is it implementation defined (you also mentioned a user-defined plugin)? If the latter, how can we ensure consistency across implementations (interoperability)?

[jdesrosiers]

It would be an application-specific plugin. The application chooses how it wants to consume the non-JRef document content. It should be purely an application concern that doesn't effect interoperability.

However, if JRef allowed for embedded documents (bundling), interoperability could become an issue depending on how the embedding feature is defined.

Example

{
  "stuff": { "$href": "./stuff.xml" }
}

./my-schema.xml

<xml>
 <stuff/>
</xml>

If you try to embed this reference, you'd end up with something like this.

{
  "stuff": "<xml><stuff/></xml>"
}

If you did this, you'd loose the context that the value is an XML document encoded as a string and there would have to be some interoperable feature added to recognize that this was an XML document.

For example

{
  "stuff": {
    "$href": "./stuff.xml",
    "$contentType": "application/xml",
    "$content": "<xml><stuff/></xml>"
  }
}

I don't see any reason why this would be preferred over the tar solution to bundling I mentioned, so it seemed best to just not complicate things by including an embedding feature.