[FOLIO-573] Use a consistent method for RAML to refer to a parent JSON schema which refers to another JSON schema Created: 25/Apr/17  Updated: 12/Nov/18  Resolved: 09/Aug/17

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Bug Priority: P3
Reporter: David Crossley Assignee: David Crossley
Resolution: Done Votes: 0
Labels: raml
Remaining Estimate: Not Specified
Time Spent: 1 week, 2 days, 3 hours, 20 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-912 Improve configuration for RAML schema... Open
relates to FOLIO-523 Decide if FOLIO should enable using R... Closed
relates to FOLIO-1213 Using an "id" property in JSON Schema... Closed
relates to FOLIO-1399 Improve lint-raml to handle RMB v20+ ... Closed
relates to FOLIO-1490 Enable various tools for validation a... Closed
relates to RMB-30 Trouble with a schema file referring ... Closed
relates to RMB-109 RAML 1.0 support: use raml-for-jax-rs... Closed
Sprint:

 Description   

Our RAML files do "!include" a JSON schema file in another directory,
and that schema refers to another schema in a separate file.

There are two methods to link those two schema. The current suite of RAML tools only partially handle these methods.

So we currently need a pre-processing workaround to be able to use those other tools.



 Comments   
Comment by David Crossley [ 25/Apr/17 ]

There are two methods for the parent schema to refer to the second schema:

A) By schema key –

"$ref": "petSchema"

(i.e. As declared in the top-level RAML file.)

B) By filename –

"$ref": "pet.json"

We currently use method A.

That is successful with the current version of "raml-for-jax-rs" (v1.3.4) that we use with the RMB. Its dependency is "raml-parser-2" (i.e. raml-java-parser).

However for other tools that depend on "raml-js-parser-2" (i.e. "raml-1-parser") that method does not work. These include validation tools such as "raml-cop" and "eslint-raml", and editors such as "api-workbench" for the Atom text editor, and "api-designer".

The method B does work for the tools based on "raml-js-parser-2". However not for "raml-for-jax-rs".
This seems to be a long-standing problem, e.g. see
raml-for-jax-rs/issues/202 and related ones.

For the upcoming "raml-for-jax-rs" v2.0.0 both methods work for RAML-0.8 version, and neither currently work for RAML-1.0 version.

Comment by David Crossley [ 25/Apr/17 ]

So to completely validate our RAMLs and their examples, or to use a RAML editor, we currently need to pre-process them to replace those "key" $ref values with their equivalent filename. See FOLIO-1490 Closed .

Comment by David Crossley [ 25/Apr/17 ]

Some relevant issues:

raml-for-jax-rs/issues/202

raml-java-parser/issues/362

raml-js-parser-2/issues/726

raml2html/issues/327

Comment by David Crossley [ 27/Apr/17 ]

The raml-js-parser-2/issues/726 is now closed as "Won't fix". That has a clear explanation of the reason.

So the focus is on raml-for-jax-rs/issues/202 being able to handle Method #B.

Note from that issue, raml-for-jax-rs 2.0.0 (which was released a few days ago) does handle that for RAML-0.8 version.

Comment by David Crossley [ 08/May/17 ]

There is a workaround. For each schema file that is referenced from another schema file, commit to git a symbolic link. That enables everything to stay as-is, and also enables the editors and tools to operate.

Comment by David Crossley [ 09/May/17 ]

A neater workaround is to rename every schema/* file to be exactly the same filename as the "key" name in the RAML "schemas" section.

Comment by David Crossley [ 10/May/17 ]

Decided on the symlink technique, and a README.md in each schema directory.

Also a raml-util git submodule might get updated before this transition is completed, so this technique enables it to operate either way.

Comment by David Crossley [ 13/May/17 ]

Now done the symlink workaround for most raml-using repositories. Not yet RMB.

The raml-util still needs update for some repos (RMB, okapi, mod-configuration, mod-acquisitions, mod-circulation)

Comment by David Crossley [ 19/May/17 ]

There is a better solution. When any schema file refers to an additional schema file, then use the filename of that referenced second schema as the "key" name in the RAML "schemas" section, and wherever that schema is utilised in RAML and schema files.

Comment by David Crossley [ 24/May/17 ]

Done that now for folio-org/raml (i.e. raml-util).

This naming scheme could be applied to other entries in RAML "schemas" sections, so as to reduce confusion as to why some do use the filename and some do not. Not done that, as there are some existing ones that do not match the naming pattern. Added a note to raml/schemas/README.md

Comment by David Crossley [ 31/May/17 ]

That is now done for all raml-using repositories, except raml-module-builder.

A new issue arose ( RMB-30 Closed ) when using a relative path to a separate schema in the shared "raml-util".

Comment by David Crossley [ 08/Aug/17 ]

See mod-notes as an exemplar, and notes in RMB readme.

Comment by David Crossley [ 09/Aug/17 ]

Closed.

With the combination of solving RMB-30 Closed , and this FOLIO-573 Closed using pathname for $ref in schema, all raml-related tools can now operate.

Generated at Thu Feb 08 23:06:47 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.