[FOLIO-3541] JSON Schema extension attributes are omitted from generated documentation Created: 20/Jul/22  Updated: 27/Jul/22  Resolved: 27/Jul/22

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

Type: Story Priority: TBD
Reporter: Zak Burke Assignee: David Crossley
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-3543 Rebuild folioci/jenkins-slave-all for... Closed
Sprint: DevOps Sprint 144, DevOps Sprint 145
Development Team: FOLIO DevOps
RCA Group: TBD

 Description   

Summary: Documentation generated from JSON schemas does not include our schema-extending keywords related to mod-graphql.

Details: mod-graphql uses several JSON Schema extension keywords that are leveraged by modules (e.g. mod-inventory-storage). These fields may behave differently than other fields in an API response (e.g. a field with "folio:isVirtual": true will not be populated) but there is no way to know this because the extension keywords are not present.

This omission caused quite a lot of confusion among SMEs and developers who were familiar with the generated API documentation for mod-inventory-storage but not the JSON schema files it derives from.

Expected behavior: All attributes that affect a field's behavior are included in documentation derived from its JSON schema (.json) files.

Actual behavior: Some attributes are omitted, including all folio:* attributes.

CC: Mike Taylor, Marc Johnson



 Comments   
Comment by David Crossley [ 21/Jul/22 ]

One example of this documentation lack is here. Scroll down a little to "permanentLocation". Note that its "location.json" schema has not been expanded (dereferenced). Whereas for the "permanentLocationId" just above it, the "uuid.json" schema has been properly dereferenced.

This is the relevant section of the holdingsrecord.json schema:

    "permanentLocationId": {
      "type": "string",
      "description": "The permanent shelving location in which an item resides.",
      "$ref" : "uuid.json"
    },
    "permanentLocation": {
      "description": "The permanent shelving location in which an item resides",
      "type": "object",
      "folio:$ref": "location.json",
      "readonly": true,
      "folio:isVirtual": true,
      "folio:linkBase": "locations",
      "folio:linkFromField": "permanentLocationId",
      "folio:linkToField": "id",
      "folio:includedElement": "locations.0"
    },

The difference is in how the "$ref" is declared.

When the "api-doc" tool processes that RAML file, it utilises json-schema-ref-parser to dereference the schemas beforehand.

This is the relevant section of api-doc, where it calls our deref-schema.js nodejs script. I presume that it does not recognise the "folio:$ref" but does handle the normal "$ref" pointer.

Mike Taylor – Would it be possible for mod-graphql to use the normal "$ref" instead? I did search the repo and found Adam's note in doc/fixing-schema-collisions.txt wondering about the same.

If not, then would someone (e.g. Mike Taylor or Zak Burke) please assist to enhance our deref-schema.js to handle the "folio:$ref" pointers. My JS skills are minimal.

Comment by David Crossley [ 23/Jul/22 ]

Hooray, i found a solution. The api-doc Python tool will scan all of a repository's JSON Schema files and temporarily replace with "$ref" before processing to generate each API documentation.

(It will take some time to roll out to the Jenkins CI, as we need to rebuild its docker image.)

Comment by David Crossley [ 27/Jul/22 ]

This is now deployed to Jenkins CI. The mod-inventory-storage API documentation is now regenerated and published with this fix.

Note that this applies universally. So for any other repository that would utilise the "folio:$ref" style of schema references, this is handled for their API documentation purpose.

Comment by Marc Johnson [ 27/Jul/22 ]

David Crossley

Hooray, i found a solution. The api-doc Python tool will scan all of a repository's JSON Schema files and temporarily replace with "$ref" before processing to generate each API documentation.

Thanks, this is a neat solution

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