<!-- 
RSS generated by JIRA (1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d) at Thu Feb 08 23:28:54 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary add field=key&field=summary to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>FOLIO Jira</title>
    <link>https://folio-org.atlassian.net</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>1001.0.0-SNAPSHOT</version>
        <build-number>100246</build-number>
        <build-date>07-02-2024</build-date>
    </build-info>

<item>
            <title>[FOLIO-3541] JSON Schema extension attributes are omitted from generated documentation</title>
                <link>https://folio-org.atlassian.net/browse/FOLIO-3541</link>
                <project id="10290" key="FOLIO">FOLIO</project>
                    <description>&lt;p&gt;&lt;b&gt;Summary:&lt;/b&gt; Documentation generated from JSON schemas does not include our schema-extending keywords related to mod-graphql.&lt;/p&gt;

&lt;p&gt;&lt;b&gt;Details:&lt;/b&gt; &lt;tt&gt;mod-graphql&lt;/tt&gt; uses several &lt;a href=&quot;https://github.com/folio-org/mod-graphql/blob/124d0c0fbbf3092ea93af156dec40ee326f88483/src/autogen/README.md#option-1-json-schema-extensions&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;JSON Schema extension keywords&lt;/a&gt; that are leveraged by modules (e.g. &lt;a href=&quot;https://github.com/folio-org/mod-inventory-storage/blob/01aac2881cd72bcdaf8468746c537ec46753f180/ramls/holdingsrecord.json#L320-L324&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;mod-inventory-storage&lt;/a&gt;). These fields may behave differently than other fields in an API response (e.g. a field with &lt;tt&gt;&quot;folio:isVirtual&quot;: true&lt;/tt&gt; will not be populated) but there is no way to know this because the extension keywords are not present. &lt;/p&gt;

&lt;p&gt;This omission &lt;a href=&quot;https://folio-project.slack.com/archives/C031HF7RW01/p1658308402022479&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;caused quite a lot of confusion among SMEs and developers&lt;/a&gt; who were familiar with the generated API documentation for &lt;tt&gt;mod-inventory-storage&lt;/tt&gt; but not the JSON schema files it derives from.&lt;/p&gt;

&lt;p&gt;&lt;b&gt;Expected behavior:&lt;/b&gt; All attributes that affect a field&apos;s behavior are included in documentation derived from its JSON schema (&lt;tt&gt;.json&lt;/tt&gt;) files. &lt;/p&gt;

&lt;p&gt;&lt;b&gt;Actual behavior:&lt;/b&gt; Some attributes are omitted, including all &lt;tt&gt;folio:*&lt;/tt&gt; attributes.&lt;/p&gt;

&lt;p&gt;CC: &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5bffed52a1b46046f530c8f7&quot; class=&quot;user-hover&quot; rel=&quot;5bffed52a1b46046f530c8f7&quot; data-account-id=&quot;5bffed52a1b46046f530c8f7&quot; accountid=&quot;5bffed52a1b46046f530c8f7&quot; rel=&quot;noreferrer&quot;&gt;Mike Taylor&lt;/a&gt;, &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=63e2a2771b13d42998e4e706&quot; class=&quot;user-hover&quot; rel=&quot;63e2a2771b13d42998e4e706&quot; data-account-id=&quot;63e2a2771b13d42998e4e706&quot; accountid=&quot;63e2a2771b13d42998e4e706&quot; rel=&quot;noreferrer&quot;&gt;Marc Johnson&lt;/a&gt;&lt;/p&gt;</description>
                <environment></environment>
        <key id="82402">FOLIO-3541</key>
            <summary>JSON Schema extension attributes are omitted from generated documentation</summary>
                <type id="10005" iconUrl="https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10309?size=medium">Story</type>
                                            <priority id="10005" iconUrl="https://dev.folio.org/assets/jira-priority/tbd.svg">TBD</priority>
                        <status id="6" iconUrl="https://folio-org.atlassian.net/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="green"/>
                                    <resolution id="10003">Done</resolution>
                                                        <assignee accountid="61cd0ca0bce5e00069e98be7">David Crossley</assignee>
                                                                <reporter accountid="615afd1cd9820f0070a09ef0">Zak Burke</reporter>
                                    <labels>
                    </labels>
                <created>Wed, 20 Jul 2022 13:21:20 +0000</created>
                <updated>Wed, 27 Jul 2022 09:38:59 +0000</updated>
                            <resolved>Wed, 27 Jul 2022 04:45:25 +0000</resolved>
                                                                        <due></due>
                            <votes>0</votes>
                                    <watches>2</watches>
                                                                <comments>
                                                            <comment id="198101" author="61cd0ca0bce5e00069e98be7" created="Thu, 21 Jul 2022 06:45:55 +0000"  >&lt;p&gt;One example of this documentation lack is &lt;a href=&quot;https://s3.amazonaws.com/foliodocs/api/mod-inventory-storage/p/holdings-storage.html#holdings_storage_holdings__holdingsrecordid__get&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;here&lt;/a&gt;. Scroll down a little to &quot;permanentLocation&quot;. Note that its &quot;location.json&quot; schema has not been expanded (dereferenced). Whereas for the &quot;permanentLocationId&quot; just above it, the &quot;uuid.json&quot; schema has been properly dereferenced.&lt;/p&gt;

&lt;p&gt;This is the &lt;a href=&quot;https://github.com/folio-org/mod-inventory-storage/blob/5469c29f2da9148c312d1aefe27359c43e1343c4/ramls/holdingsrecord.json#L37-L52&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;relevant section&lt;/a&gt; of the holdingsrecord.json schema:&lt;/p&gt;

&lt;div class=&quot;code panel&quot; style=&quot;border-width: 1px;&quot;&gt;&lt;div class=&quot;codeContent panelContent&quot;&gt;
&lt;pre class=&quot;code-java&quot;&gt;
    &lt;span class=&quot;code-quote&quot;&gt;&quot;permanentLocationId&quot;&lt;/span&gt;: {
      &lt;span class=&quot;code-quote&quot;&gt;&quot;type&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;string&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;description&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;The permanent shelving location in which an item resides.&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;$ref&quot;&lt;/span&gt; : &lt;span class=&quot;code-quote&quot;&gt;&quot;uuid.json&quot;&lt;/span&gt;
    },
    &lt;span class=&quot;code-quote&quot;&gt;&quot;permanentLocation&quot;&lt;/span&gt;: {
      &lt;span class=&quot;code-quote&quot;&gt;&quot;description&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;The permanent shelving location in which an item resides&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;type&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;object&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:$ref&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;location.json&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;readonly&quot;&lt;/span&gt;: &lt;span class=&quot;code-keyword&quot;&gt;true&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:isVirtual&quot;&lt;/span&gt;: &lt;span class=&quot;code-keyword&quot;&gt;true&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:linkBase&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;locations&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:linkFromField&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;permanentLocationId&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:linkToField&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;id&quot;&lt;/span&gt;,
      &lt;span class=&quot;code-quote&quot;&gt;&quot;folio:includedElement&quot;&lt;/span&gt;: &lt;span class=&quot;code-quote&quot;&gt;&quot;locations.0&quot;&lt;/span&gt;
    },
&lt;/pre&gt;
&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The difference is in how the &quot;$ref&quot; is declared.&lt;/p&gt;

&lt;p&gt;When the &quot;&lt;a href=&quot;https://dev.folio.org/guides/api-doc/&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;api-doc&lt;/a&gt;&quot; tool processes that RAML file, it utilises &lt;a href=&quot;https://github.com/APIDevTools/json-schema-ref-parser&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;json-schema-ref-parser&lt;/a&gt; to dereference the schemas beforehand.&lt;/p&gt;

&lt;p&gt;This is the &lt;a href=&quot;https://github.com/folio-org/folio-tools/blob/709100047cd9ce9cd730bcdc912ac625abbf4cd0/api-doc/api_doc.py#L219&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;relevant section&lt;/a&gt; of api-doc, where it calls our &lt;a href=&quot;https://github.com/folio-org/folio-tools/blob/master/api-doc/deref-schema.js&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;deref-schema.js&lt;/a&gt; nodejs script. I presume that it does not recognise the &quot;folio:$ref&quot; but does handle the normal &quot;$ref&quot; pointer.&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5bffed52a1b46046f530c8f7&quot; class=&quot;user-hover&quot; rel=&quot;5bffed52a1b46046f530c8f7&quot; data-account-id=&quot;5bffed52a1b46046f530c8f7&quot; accountid=&quot;5bffed52a1b46046f530c8f7&quot; rel=&quot;noreferrer&quot;&gt;Mike Taylor&lt;/a&gt; &amp;#8211; Would it be possible for mod-graphql to use the normal &quot;$ref&quot; instead? I did search the repo and found Adam&apos;s note in &lt;a href=&quot;https://github.com/folio-org/mod-graphql/blob/5456328943dcf4dea485063c4075eb28ae298495/doc/fixing-schema-collisions.txt#L67&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;doc/fixing-schema-collisions.txt&lt;/a&gt; wondering about the same.&lt;/p&gt;

&lt;p&gt;If not, then would someone (e.g. &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5bffed52a1b46046f530c8f7&quot; class=&quot;user-hover&quot; rel=&quot;5bffed52a1b46046f530c8f7&quot; data-account-id=&quot;5bffed52a1b46046f530c8f7&quot; accountid=&quot;5bffed52a1b46046f530c8f7&quot; rel=&quot;noreferrer&quot;&gt;Mike Taylor&lt;/a&gt; or &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=615afd1cd9820f0070a09ef0&quot; class=&quot;user-hover&quot; rel=&quot;615afd1cd9820f0070a09ef0&quot; data-account-id=&quot;615afd1cd9820f0070a09ef0&quot; accountid=&quot;615afd1cd9820f0070a09ef0&quot; rel=&quot;noreferrer&quot;&gt;Zak Burke&lt;/a&gt;) please assist to enhance our deref-schema.js to handle the &quot;folio:$ref&quot; pointers. My JS skills are minimal.&lt;/p&gt;</comment>
                                                            <comment id="198102" author="61cd0ca0bce5e00069e98be7" created="Sat, 23 Jul 2022 04:47:25 +0000"  >&lt;p&gt;Hooray, i found a solution. The api-doc Python tool will scan all of a repository&apos;s JSON Schema files and temporarily replace with &quot;$ref&quot; before processing to generate each API documentation.&lt;/p&gt;

&lt;p&gt;(It will take some time to roll out to the Jenkins CI, as we need to rebuild its docker image.)&lt;/p&gt;</comment>
                                                            <comment id="198103" author="61cd0ca0bce5e00069e98be7" created="Wed, 27 Jul 2022 04:45:09 +0000"  >&lt;p&gt;This is now deployed to Jenkins CI. The mod-inventory-storage API documentation is now regenerated and published with this fix.&lt;/p&gt;

&lt;p&gt;Note that this applies universally. So for any other repository that would utilise the &quot;folio:$ref&quot; style of schema references, this is handled for their API documentation purpose.&lt;/p&gt;</comment>
                                                            <comment id="198104" author="63e2a2771b13d42998e4e706" created="Wed, 27 Jul 2022 09:38:59 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=61cd0ca0bce5e00069e98be7&quot; class=&quot;user-hover&quot; rel=&quot;61cd0ca0bce5e00069e98be7&quot; data-account-id=&quot;61cd0ca0bce5e00069e98be7&quot; accountid=&quot;61cd0ca0bce5e00069e98be7&quot; rel=&quot;noreferrer&quot;&gt;David Crossley&lt;/a&gt;&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;Hooray, i found a solution. The api-doc Python tool will scan all of a repository&apos;s JSON Schema files and temporarily replace with &quot;$ref&quot; before processing to generate each API documentation.&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;Thanks, this is a neat solution&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10003">
                    <name>Relates</name>
                                                                <inwardlinks description="relates to">
                                        <issuelink>
            <issuekey id="82403">FOLIO-3543</issuekey>
        </issuelink>
                            </inwardlinks>
                                    </issuelinktype>
                    </issuelinks>
                <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_10000" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummarycf">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10057" key="com.atlassian.jira.plugin.system.customfieldtypes:select">
                        <customfieldname>Development Team</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10155"><![CDATA[FOLIO DevOps]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10063" key="com.atlassian.jira.plugin.system.customfieldtypes:float">
                        <customfieldname>PO Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>0.0</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                    <customfield id="customfield_10106" key="com.atlassian.jira.plugin.system.customfieldtypes:select">
                        <customfieldname>RCA Group</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10367"><![CDATA[TBD]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_10019" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>0|i053qs:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_10020" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="1971">DevOps Sprint 144</customfieldvalue>
    <customfieldvalue id="2007">DevOps Sprint 145</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_10024" key="com.atlassian.jira.ext.charting:firstresponsedate">
                        <customfieldname>[CHART] Date of First Response</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>Thu, 21 Jul 2022 06:45:55 +0000</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10025" key="com.atlassian.jira.ext.charting:timeinstatus">
                        <customfieldname>[CHART] Time in Status</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                    </customfields>
    </item>
</channel>
</rss>