Support for relative references

[skh-]

dtsgenerator creates some really great definitions. I'm having some issues with the $ref implementation requiring a top-level id.

OpenAPI defines the $ref: using the URL of the current document as the base URI. Setting the $ref value to match a dtsgenerator-only-syntax matching an id: causes trouble using this with any other OpenAPI software.

The base cause is that this is not valid a OpenAPI v3 schema. IE running it through something like swagger-parser will fail validation.

Consider this structure:

src/
- api.yaml
|-- components/
|---- models/
|------ Auth.yaml
|---- responses/
|------ Response.yaml

Assume that:

1. Api.yaml has a $ref to Response.yaml and Auth.yaml
2. Response.yaml has a $ref to Auth.yaml.

If I set the id:'s and ref:'s to /Auth.yaml and /Response.yaml, it will work with dtsgenerator.

However, this will fail OpenAPI validation (id: property not valid, and eg. /Auth.yaml not found on disk.) and make this schema unusable with most other Open API packages.

If I set the $ref to the follow the proper spec:

• in Api.yaml:
  • ./components/responses/Response.yaml,
  • ./components/models/Auth.yaml
• in Response.yaml:
  • ../models/Auth.yaml

Then it will follow the spec and work with most other packages, but fail with dtsgenerator. There is no way to match the id: property, since Auth.yaml is referenced from two different places.

I'm sure there is a good reason why id is required - but is there no way to use this package using the spec-defined implementation of $ref? Or a workaround? Or am I doing something wrong?

Thanks for the great work!

[horiuchi]

Thank you for using the dtsgenerator.

The $ref implementation is based on the JSON-Schema specification.
via. http://json-schema.org/latest/json-schema-core.html#rfc.section.8.3
This spec is not included the local file referenced pattern but included URI pattern.
Thus, that pattern is the own implementation of dtsgenerator.

And about Open API support, it is used by the JSON-Schema implementation almost without change.
If you know the library for the reference implementation, let me know!

[Orodan]

+1, I got the same issue and it's stopping me from generating types with dtsgenerator.

@skh- can you provide a more detailed explanation on how you manage to make it work with an id ? I could use it as a temporary workaround bu I can't found a working example

[adriengibrat]

Hi @skh- & @Orodan,
using external files $ref & https://www.npmjs.com/package/swagger-cli bundle to aggregate files could be a good alternative?

[ogonkov]

Several keywords can accept a relative URI-reference, or a value used to construct a relative URI-reference. For these keywords, it is necessary to establish a base URI in order to resolve the reference.
...
The value of the "$ref" keyword MUST be a string which is a URI-Reference. Resolved against the current URI base

Looks like $ref could be relative