Counterpart of dereferenceSchemas in raml-js-parser-2 ?

[tfayruzov]

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.

[ddenisenko]

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?

[tfayruzov]

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.

[cascer1]

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.

[tfayruzov]

@cascer1 Were you able to figure out how to dereference the schemas manually? It seems that some support for that was added (schemaPathand 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 #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.

[ddenisenko]

@tfayruzov

There's very little useful documentation. What's the difference between loadApi and loadRAML?

Documentation for loadApi.

Documentation for 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?

[tfayruzov]

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.

[ddenisenko]

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.

[tfayruzov]

ok, looking forward to the solution.

[MikeTaylor]

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

[postatum]

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.