[FOLIO-2814] Investigate use of "id" keyword and "$ref" keyword in JSON Schema Created: 01/Oct/20  Updated: 09/Oct/20

Status: In Progress
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: TBD
Reporter: David Crossley Assignee: David Crossley
Resolution: Unresolved Votes: 0
Labels: raml
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to OKAPI-914 Enable standalone schema validation o... Closed
relates to FOLIO-2792 Investigate AMF "validate" facility t... Closed
Sprint:
Development Team: FOLIO DevOps

 Description   

The current set of JSON Schema files have no "id" keyword, and use the "$ref" keyword with a relative pathname to link between parent schema and child schema files.

That configuration does operate successfully with the current RAML Module Builder RMB, and with the "lint-raml" facility in FOLIO CI to assess the RAML/JSON Schema.

That "lint-raml" facility uses the "raml-1-parser" (i.e. raml-js-parser-2 current version v1.1.67) and its dependency, the schema validator z-schema

z-schema can also be used independently to validate these schema, and to assess examples against their schema.

However ajv cannot be utilised, as it requires "id" keyword in the schema.

Also the new AMF tools for processing RAML/Schema (see FOLIO-2792 Closed e.g. amf-client-js and webapi-parser) seem to require "id" keywords in some cases.

Conduct some investigations to potentially improve this situation.



 Comments   
Comment by David Crossley [ 09/Oct/20 ]

The use of "$ref" to link between parent and child JSON Schema has been a bane of our project.

There are many other FOLIO Jira tickets related to this general issue about "$ref". They are difficult to find with Jira limited search. This search gets close.
To assist, here are some of the main ones (no special order): RMB-203 Closed RMB-56 Closed FOLIO-1220 Closed RMB-30 Closed FOLIO-573 Closed FOLIO-1040 Closed

There are also many other places that refer to the complexities of "$ref" and "id". This is a list of some:
https://github.com/ajv-validator/ajv#ref – Combining schemas with $ref
https://github.com/json-schema-org/json-schema-spec/issues/66 – Determine behavior of $ref
https://github.com/json-schema-org/json-schema-spec/issues/160 – Simplify schema re-use

Comment by David Crossley [ 09/Oct/20 ]

With the aforementioned FOLIO tickets, we settled on the use of "pathname" and avoiding the use of dotdots ("../") – so child schema would be below their parent schema.

One aspect that helped, is to have the shared "raml-util" submodule inside the "ramls" directory (i.e. ramls/raml-util).

Now there are also various other shared RAML/Schema git submodules, so it has become even more complex.

Comment by David Crossley [ 09/Oct/20 ]

Adding "id" keyword to schema is difficult in some cases where the same schema is referenced from different places.

So handling that task in small chunks.

One that was easier to handle was OKAPI-914 Closed for schema related to ModuleDescriptor etc. That set of schema is self-contained. Now ajv validator can be used there.

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