Open jdesrosiers opened 1 year ago
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)?
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.
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.
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
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:
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
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 https://github.com/json-schema-org/referencing/issues/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.
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.