[FOLIO-1447] FOLIO policy for RAML and JSON descriptions Created: 29/Aug/18  Updated: 07/Feb/19

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

Type: New Feature Priority: P3
Reporter: Tod Olson Assignee: David Crossley
Resolution: Unresolved Votes: 0
Labels: ci, core, potential-q1, sprint, sprint47, sprint48, sprint49, sprint50, sprint51, sprint52, sprint53, sprint54
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-1554 Add JSON descriptions to raml-util sc... Open
relates to MODFEE-9 Use description fields in RAML JSON s... Open
relates to MODLOGSAML-37 Use description fields in RAML JSON s... Open
relates to MODUIMP-5 Use description fields in RAML JSON s... Open
relates to MODINV-87 Use description fields in JSON schemas Closed
relates to CIRC-142 Use description fields in JSON schemas Closed
relates to CIRCSTORE-75 Use description fields in JSON schemas Closed
relates to EDGPATRON-4 Use description fields in RAML JSON s... Closed
relates to FOLIO-1410 Use dedicated Sonarqube Github user f... Closed
relates to MODCAL-20 Use description fields in RAML JSON s... Closed
relates to MODCXINV-37 Use description fields in RAML JSON s... Closed
relates to MODDATAIMP-31 Use description fields in RAML JSON s... Closed
relates to MODEUS-33 Use description fields in RAML JSON s... Closed
relates to MODINVSTOR-179 Document properties of instance, hold... Closed
relates to MODINVSTOR-203 Use description fields in JSON schemas Closed
relates to MODLOGIN-85 Use description fields in RAML JSON s... Closed
relates to MODNOTIFY-40 Use description fields in RAML JSON s... Closed
relates to MODORDSTOR-12 Missing JSON schema "description" fie... Closed
relates to MODPATRON-11 Use description fields in RAML JSON s... Closed
relates to MODPERMS-48 Use description fields in RAML JSON s... Closed
relates to MODRTAC-5 Use description fields in RAML JSON s... Closed
relates to MODTAG-11 Use description fields in RAML JSON s... Closed
relates to MODUSERBL-46 Use description fields in RAML JSON s... Closed
relates to OKAPI-241 Use description field in JSON schemas Closed
relates to MODCONF-27 Add descriptions to schemas Open
relates to RMB-287 Remove old sample.raml Open
relates to UXPROD-1414 Complete the documentation of data at... Closed
relates to FOLIO-1481 Move CI job lint-raml to before maven Closed
relates to FOLIO-1551 Missing or incomplete documentation o... Closed
relates to MODUSERS-87 Document backend fields Closed
relates to RMB-282 Use description fields in RAML JSON s... Closed
Sprint:
Development Team: Core: Platform

 Description   

Set policies to encourage supplying descriptions in RAML and JSON schema.

These descriptions are useful documentation and the project needs some policies to encourage supplying the descriptions. They are particularly useful for people getting familiar with a module, for example in planning data migration.

Related to OKAPI-241 Closed .



 Comments   
Comment by Jakub Skoczen [ 18/Sep/18 ]

David Crossley can we add a rule in the raml linter to warn about missing description fields in the JSON schema?

Comment by David Crossley [ 19/Sep/18 ]

Got something basic happening.

The lint-raml CI job operates on branch builds and PRs.

It now also finds all schemas, ensures top-level "description" and assesses "properties" to ensure a description for each.

Currently only as warnings. So it will only be seen on the GitHub if there are also raml-cop errors.

So see the report of a recent build by following through to the Jenkins output and see "Artifacts" at the top-right.

It excludes "metadata, resultInfo, totalRecords" (can add others).
Although note that the most complete example does have description for "metadata".
https://github.com/folio-org/mod-circulation-storage/blob/master/ramls/loan.json

It only investigates top-level "properties", not any nested.

Excluded all of "acq-models" for now.

Comment by David Crossley [ 28/Sep/18 ]

The lint-raml CI job now logs errors for the missing JSON schema description fields.
So will now also display the messages via the GitHub pull request screen.

It does not cause the Jenkins build stage to fail. It will just show the errors.

Comment by David Crossley [ 01/Oct/18 ]

Now it assesses the nested properties.

Comment by David Crossley [ 01/Oct/18 ]

There is a basic document at dev.folio.org/guides/describe-schema/

Comment by David Crossley [ 02/Nov/18 ]

The document at dev.folio.org/guides/describe-schema/ has been improved, and also linked back to these issues (this FOLIO-1447 Blocked and FOLIO-1551 Closed ) for further guidance.

Note that this lint-raml CI job only assesses missing "description" fields.

Comment by Marc Johnson [ 08/Nov/18 ]

David Crossley I would like to be able to check the general validity of the RAML and schema before checking for missing descriptions.

Is it already possible to skip those checks? Or if not, would it be possibly to add a parameter to disable the checks for for missing description properties in the lint-raml.py script.

Comment by David Crossley [ 09/Nov/18 ]

Sure Marc. That is done now, so use the arg "--validate-only" (i.e. -v).

Comment by Marc Johnson [ 09/Nov/18 ]

David Crossley Thanks, that works great

Comment by Jakub Skoczen [ 11/Dec/18 ]

The missing description issues should be addressed in Q1.

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