[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: |
|
||||||||||||||||||||||||||||||||
| Sprint: | |||||||||||||||||||||||||||||||||
| Description |
|
Our RAML files do "!include" a JSON schema file in another directory, 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". 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
|
| Comment by David Crossley [ 25/Apr/17 ] |
|
Some relevant issues: |
| 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 (
|
| 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
|