VideosJSON Schema Search and Refactoring Actions in Oxygen XML


Duration: 07:31

The purpose of this video is to demonstrate how to use Search and Refactoring type actions in Oxygen's JSON Schema Design mode.


00:00:07The purpose of this video is to present how  to use Search and Refactoring type actions  
00:00:12in Oxygen's JSON Schema Design mode. For this  demonstration, I have 3 sample schema files  
00:00:18that are designed to validate JSON files that  contain information about books from a library.
00:00:25I'll start by opening the lib-items schema file,  
00:00:29I'll right-click and choose  Expand All to expand the diagram.  
00:00:33This sample schema considers the book ID ... the  publishing house ... and the book description.
00:00:41Then I'll open the  borrowed-books schema, expand it,  
00:00:48and this one considers a book  reference code ... and the publisher.
00:00:53And I'll open the lib-books schema file, and it  considers the title ... genre ... and authors.
00:01:08When writing JSON schemas, it is considered a good  practice to use the definitions section to group  
00:01:13sub-schemas with descriptive names that can be  referenced where needed, using the $ref keyword. 
00:01:19Definitions and references are good for  avoiding duplication and allow users to  
00:01:23write schemas that are easier to read and  maintain. It's also a common practice for  
00:01:28related schemas to share definitions ...  referencing them through the $ref keyword.  
00:01:33So, I will show you that Oxygen  includes some actions in the Design  
00:01:36mode's contextual menu that could prove to  be useful for working with such constructs.
00:01:42For example, suppose that I want to see all  the occurrences of a particular definition.  
00:01:47I'll right-click the  mediumLengthString definition,  
00:01:51I'll go to the Search submenu, and I'll  select "Search occurrences in file".
00:01:58All occurrences of components within the  diagram that use the mediumLengthString  
00:02:02name are listed in the bottom results  pane ... and if I click on each one,  
00:02:07you can see that it highlights the  particular occurrence in the document.
00:02:16I'll right-click that same definition again,  
00:02:19and go to the Search submenu, and this time  I'll select Search References. This action  
00:02:25searches for all references of the selected  definition in a scope determined by the  
00:02:29schemas referenced in the file and the schemas  declared in associated validation scenarios.
00:02:35Again, I'll click on the occurrences,  
00:02:38and notice that the 3rd one switched focus to the  publishingHouse property from another file, the  
00:02:45lib-items schema file. So, the mediumLengthString  definition is shared between the two schema files.
00:02:51In regard to the scope of the search  action, it searches the current schema file,  
00:02:57then it searches other schema files  that are referenced in the current file,  
00:03:01and then it searches schema files that are  declared in associated validation scenarios.
00:03:07In my case, the 2nd criterion is  the one responsible for including  
00:03:10the lib-items schema in the scope of the action.
00:03:14Indeed, you can see that the  ID property in the lib-books  
00:03:17file contains a reference to the ID  definition from the lib-items file.  
00:03:23As I mentioned earlier, the 2 schemas  share some of their definition constructs.
00:03:29Now, it may not be able to detect all the  references of a certain definition since the scope  
00:03:33is strictly defined by the criteria I mentioned  a minute ago. But, to broaden the search scope,  
00:03:38I can use the "Search References in" action.  It is also found in the Search submenu.
00:03:45The resulting dialog box allows you to provide  a custom scope for the search operation.  
00:03:50I'll select the Working Sets  option, I'll click New working set,  
00:03:56I'll name it lib-scope and press ENTER, then  I'll click Add Resources, I'll chose Folders,  
00:04:05and it automatically chose the correct  path to my lib folder so I'll click Choose.
00:04:12Then I'll click Search and again the results  are listed in bottom pane. Compared to the  
00:04:17previous search, an additional result was  found this time. It's the first one listed,  
00:04:22and clicking it highlights the publisher  property from the borrowed-books file,  
00:04:28and you can see that it references the  mediumLengthString definition from the lib-books  
00:04:34file. So, we found that the particular definition  is used in all 3 schemas in my working directory.
00:04:42The final action I want to show you is probaby  the most useful of them. In the process of  
00:04:48designing JSON schemas, sometimes you may want to  change the names of already created definitions.  
00:04:52However, those definitions could be referenced  through their names by various other components,  
00:04:58either from the source JSON schema  file, or from other schema files,  
00:05:02as we saw in the previous example. So  a rename operation is needed that would  
00:05:06detect all references to the respective  definition within a specified scope and  
00:05:11modify the name of the definition accordingly in  all components that reference that definition.
00:05:17I'll click-click the same definition again  and this time I'll select Rename Component In.
00:05:24In the resulting dialog box, for the new  name, I'll add TYPE in capital letters  
00:05:29at the end of the name. The Rename and  Preview buttons become available, while  
00:05:35the Working sets option is selected along with  the "lib-scope" working set I created earlier.  
00:05:42I want to propagate the name change  to all files from my lib folder...
00:05:46and for this demonstration, the  scope described by "lib-scope"  
00:05:50coincides with the scope provided  by choosing the Project option.
00:05:55I can preview the proposed changes.
00:05:59and I can click on each file to see the specific  modifications to be done on that particular file,  
00:06:05and clicking the Rename button accepts all the  proposed changes and completes the operation.
00:06:12You can see that my 3 files all  have an asterisk in the editor  
00:06:15tab denoting that there are unsaved modifications.
00:06:19In this file, notice that the  "mediumLengthString" definition has been changed.
00:06:25the reference for the title  property has been changed.
00:06:28and the reference for the name  property has been changed.
00:06:33I'll save this file and go to the next one.
00:06:36notice that the reference  for the "publishingHouse"  
00:06:38property has been changed in this file.
00:06:41And in the borrowed-books file...
00:06:45notice that the reference for the  publisher property has been changed.
00:06:50One final remark ... the schemas I've been  using in the demonstration are version draft-07.
00:06:57If you are using one of the latest  versions, the 2019-09 or 2020-12 drafts,  
00:07:04then the "$defs" keyword is used instead  of "definitions", and all of the actions  
00:07:09that I showed in this demonstration work  the same on the newer schemas as well.
00:07:15That concludes the demonstration about  the search and refactoring actions  
00:07:18that are available when working with JSON  schemas in Oxygen's design mode. As always,  
00:07:23thanks for watching and we invite you to please  subscribe to our various social media channels.

Use Oxygen Feedback to ask us anything about this video.