[FOLIO-2792] Investigate AMF "validate" facility to ensure reliable project RAML/Schema files Created: 15/Sep/20  Updated: 15/Mar/21  Resolved: 15/Mar/21

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

Type: Task Priority: P3
Reporter: David Crossley Assignee: David Crossley
Resolution: Done Votes: 0
Labels: oas, raml
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-2793 Investigate AMF "translate" facility ... Open
relates to FOLIO-2814 Investigate use of "id" keyword and "... In Progress
relates to FOLIO-3017 List RAML issues with migration to ne... Closed
relates to FOLIO-2863 pipeline changes required for Spring ... Blocked
Sprint: DevOps: Sprint 97, DevOps: Sprint 99, DevOps: Sprint 101, DevOps: Sprint 100, DevOps: Sprint 105, DevOps: Sprint 103, DevOps: Sprint 102, DevOps Sprint 109, DevOps Sprint 107, DevOps Sprint 108, DevOps: Sprint 104, DevOps Sprint 106
Development Team: FOLIO DevOps

 Description   

The AMF (AML Modeling Framework) tools can process a RAML file (and its related other RAML and Schema) into a model, which can then be validated against various profiles and translated into other formats, such as OpenAPI OAS, and JSON-LD.

Translations cannot be achieved if a model does not validate, so investigate our current set of files.

The main tool is amf-client-js which is now being used for the folio-tools/api-lint ( FOLIO-2893 Closed ).



 Comments   
Comment by David Crossley [ 24/Sep/20 ]

I have done initial local processing of the set of current FOLIO RAML/JSON Schema by using the above-mentioned tools, as well as using the raml-js-parser-2 which is behind our "lint-raml" CI processing.

We have about 65 RAML-using projects, totalling about 315 RAMLs.

All files are assessed as "conforming" using our current tool.

Using these new tools about 75 files do present issues.

Some of those seem to be example files that previously were not being processed in certain contexts, and these have definite issues such as the typical comma-in-json thing, or not validating against their schema.

Others are perhaps due to new capabilities of these new tools.

Others might be due to bugs in these new tools. So i have searched for common occurrences, developed test cases, and provided those to the upstream projects. Those will be linked up to this ticket.

Remaining general improvements to our RAMLs will be described on this ticket.

Comment by David Crossley [ 24/Sep/20 ]

Initial upstream tool contributions:


https://github.com/aml-org/amf/issues/661
Unresolved reference when example has same filename as a type filename

Update: 20201001: The ticket is now acknowledged, but not yet addressed.
Update: 20201022: Their ticket is now resolved and released with AMF v4.4.0


https://github.com/aml-org/amf/issues/637
The CLI jar falsely reports true RAML conformance with some invalid files

The ticket is acknowledged, but not yet addressed.
Update: 20201029: Their ticket is now resolved and will be released with upcoming AMF v4.4.1


The JSON Schema Validator Ajv can be used to independently assess our schema and examples.
The command-line tool ajv-cli is useful to easily invoke Ajv.

However some of our JSON Schema (i.e. those in the shared raml-util) use the filename extension suffix ".schema" which ajv-cli is not happy about.
See https://github.com/ajv-validator/ajv-cli/issues/77 which now has a pending PR.

(Note that all schemas will need a "id" keyword to enable use with Ajv. Not yet addressed.)

Comment by David Crossley [ 22/Oct/20 ]

The issue mentioned above (https://github.com/aml-org/amf/issues/661 – Unresolved reference when example has same filename as a type filename) is now fixed upstream (v4.4.0).

That reduced the number of RAML files which indicated "violations" from 75 to 25.

Comment by David Crossley [ 16/Feb/21 ]

See list of migration issues at FOLIO-3017 Closed

Comment by David Crossley [ 15/Mar/21 ]

Closing this as done.

The chosen tool amf-client-js is now being used for the folio-tools/api-lint ( FOLIO-2893 Closed ) to verify both RAML and OpenAPI (OAS) API description files. See docs at https://dev.folio.org/guides/api-lint/

Note the list of migration issues for some FOLIO modules at FOLIO-3017 Closed .

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