Open tfayruzov opened 7 years ago
There is currently no way to join all JSON schemas into a single big file.
Why do you need it? Maybe there is some other way to achieve the goal?
We are building new API definitions with RAML, but those APIs use well-established JSON Schema models that are used throughout all of our systems (mostly in async event communications, not in RPC-style). API consumers are not very familiar with those models and while I agree that JSON Schema is not a very good format to document the model, it is the best what we have now. For this case, navigating nested schemas is awkward (as it is not supported by generated documentation).
Essentially, JSON schemas are opaque blobs for RAML and that limits the integrations that we would like to do.
Ideally, I would like to have a datatype that is defined as JSON Schema (possible today) and can also be referenced by JSON Schema id. In the other datatype or method body definitions that use JSON Schema, parser would extract nested $refs and backreference them to corresponding data types. For example:
types:
User:
type: !include user.schema # id: "example.com/schema/user"
description: This is a user
Account:
type: !include account.schema # id: "example.com/schema/user"
description: This is an account
/transaction:
post:
body:
type: !include transaction.schema # this schema has $refs to user and account by id
Now, in generated API documentation I would be able to navigate to User and Account from Transaction. This functionality is implemented for RAML 1.0 data types, but we can't move all our data model definitions to RAML for multiple reasons. I believe that such integration will be appealing for many people who use JSON Schema as there are no good tools for generating documentation from schemas on the market, and for RAML tooling its just an incremental step that (in my opinion) brings an enormous value.
I'm also waiting for some JSON schema parsing functionality. Having to manually dereference schemas and figure out where everything goes adds a lot of mess to the code since we're going back and forth between the raw spec and parsed result.
@cascer1 Were you able to figure out how to dereference the schemas manually? It seems that some support for that was added (schemaPath
and dereference
to convert that paths to be relative to root), but it still requires manual work to actually do the dereferencing.
I'm using api-console to render RAML and it is still not clear to me how dereferencing should happen.
Api-console uses loadApi
parser method that returns JSON Schemas as strings without any metadata fields. If I make all my $refs
global I guess I can hack together the dereference process, but that's not an ideal solution. I think that there should be better tools provided by RAML parser to do so (as hinted in the issue https://github.com/raml-org/raml-js-parser-2/issues/481).
However, approaching this in RAML parser is intimidating. There's very little useful documentation. What's the difference between loadApi
and loadRAML
? One returns Api
, another BasicNode
. Is one convertible to another? There isApi
inherited from BasicNode
, but it seem to be different from the Api
returned by loadApi
. I would appreciate any pointers/advice on how can it be done more generically with the parser tools.
@tfayruzov
There's very little useful documentation. What's the difference between loadApi and loadRAML?
As we can see from the descriptuon of the methods, loadApi
loads Apis, while loadRAML
can load other types of fragments as well.
One returns Api, another BasicNode. Is one convertible to another
Documentation of Api type. As we can see right in the top of the documentation screen, Api
type is a direct descendant of the BasicNode
type.
Regarding the dereferencing: the dereferencing itself can be done by calling the dereference
function mentioned above. It operates with pure strings. If you need schemas to be joined into a single blob, this is not supported. If you need to reference RAML types from inside JSON schemas, this is not supported as well.
All in all, which format do you use: top-level or JSON, and what do you want to get as a result?
Thank you! I have seen these links, but the information there is not self-explanatory for an outsider person like me. For example, it is not clear to me what is the Typed fragment. I suspect it is types
section of RAML document, but not sure.
Further, the Api
type documentation has 08 version in the URL path and I'm using RAML 1.0. loadApi
contains a reference to both your link and https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml10parserapi_.api.html , which I assumed to be correct since it seems to be for 1.0 version?
If you need schemas to be joined into a single blob, this is not supported. If you need to reference RAML types from inside JSON schemas, this is not supported as well.
Yes I meant by that an actual [recursive] substitution of $refs with JSON blobs. I don't need to reference RAML types from JSON Schemas.
All in all, which format do you use: top-level or JSON, and what do you want to get as a result
I simply want JSON Schemas to be expanded so that a reader does not need to manually chase ref links to understand the schema, exactly the sam as it was done by dereferenceSchemas
flag in Raml 0.8 parser. This will be great to enable seamless integration of data types we defined in JSON Schemas that are used beyond APIs (see my comment form Jan 9).
Edit: I did find the https://github.com/raml-org/raml-js-parser-2/blob/master/documentation/GettingStarted.md that I missed initially , and it is a much better tool to get some basic API understanding.
I have seen these links, but the information there is not self-explanatory for an outsider person like me. For example, it is not clear to me what is the Typed fragment. I suspect it is types section of RAML document, but not sure.
Typed fragments are a part of RAML language. Here are more details in the spec: Typed fragments
Further, the Api type documentation has 08 version in the URL path and I'm using RAML 1.0. loadApi contains a reference to both your link and https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml10parserapi_.api.html , which I assumed to be correct since it seems to be for 1.0 version?
Good catch, I actually provided you with the link for 0.8 version of Api
instead of 1.0 Api
, your URL for 1.0 version of Api
is correct. In the same type hierarchy view, click on an ancestor several times starting from LibraryBase
to reach BasicNode
. Basically, BasicNode
is the root of the hierarchy.
Yes I meant by that an actual [recursive] substitution of $refs with JSON blobs. I don't need to reference RAML types from JSON Schemas.
As I said, it is not supported at the moment. It looks like more and more people ask for it, though, so we'll see what we can do.
ok, looking forward to the solution.
@ddenisenko
As I said, it is not supported at the moment. It looks like more and more people ask for it, though, so we'll see what we can do.
Hiya. I'm new to using this code, and would also find it useful to have what @tfayruzov describes. Did it ever get added?
Note that raml-js-parser-2 has been deprecated, the new official parser is webapi-parser. Feel free to attempt to reproduce this issue with webapi-parser and report any issue you may have on that repository.
I want to expand json schema definitions with refs similarly to what have been done in 0.8 parser with
dereferenceSchemas
flag. Is there a counterpart in 1.0 parser?I tried to look at the options, but it does not seem to have what I need.