VideosCreating a JSON Schema Using Design Mode and the Palette View

Overview

This video demonstrates some of the useful features that are available in Oxygen's JSON Schema Design mode when using it in conjunction with the Palette view to create a JSON schema.

Transcript

00:00:05The purpose of this video is to show you  how easy it is to create a JSON schema using  
00:00:11Oxygen's JSON Schema Design mode in conjunction  with the Palette view and we'll explore some of  
00:00:16the useful features that are available. For the purposes of this demonstration,  
00:00:21I'll use a sample JSON document that is basically  a simplified version of a larger document.  
00:00:26It contains an array of JSON objects that define  a library of books. Each book object has 3  
00:00:32properties: title, genre, and authors. Title is simply the title of the book,  
00:00:39genre is the literary genre and can be either  a single string or an array of strings,  
00:00:44and the authors property describes the  book's authors in the form of an array  
00:00:49and each object within that array has a name  and short_bio property defined as a string.
00:00:55So, I want to design a JSON schema to  validate the data from this document  
00:01:01and I'll use both Design Mode  and the Palette view to do so.  
00:01:05I'll use the new document wizard and use  the built-in JSON Schema template. 
00:01:15The document is automatically  opened in the schema Design mode  
00:01:19and it has a basic default  structure for the new JSON schema.  
00:01:24It automatically created a "properties"  group and a generic "property" within it.  
00:01:29I want to adapt it to our use-case so it should  be named books and its type should be array.  
00:01:36Now I'll define the book object inside the books  object and I'll show you how quick and easy it is  
00:01:42to add objects to the schema diagram using the  Palette view. It allows you to easily drag and  
00:01:47drop objects and make connections between them. I'll drag an "items" group from the Palette view  
00:01:54and I'll drop it to the right of the books  block. And you'll notice that throughout  
00:02:00the video, it will automatically insert  connecting lines when appropriate. 
00:02:05So, I expressed that the books array contains  items of a certain type and now I'll specify a  
00:02:11definition for that type. I'll right-click the  itemsDef object and choose Edit Properties.  
00:02:18and I'll add a reference. Note that you can double-click  
00:02:23in the property's value field or use  Ctrl-Enter to enter editing mode.  
00:02:29By the way, you can press Escape or just click  outside the pop-up to exit the editing mode.  
00:02:35Notice that we have a validation error  because the definitions group is missing. 
00:02:41So, I need to create that group and add a  definition for the book objects for that group.  
00:02:47I'll drag a definitions group from the Palette  view and drop it below the properties block.  
00:02:52Then I'll drag a definition component and drop  next to the definitions block I just created.  
00:02:59Note that it's automatically in  editing mode so I can quickly change  
00:03:02the generic default name that is proposed. Notice that the validation error is now solved.  
00:03:11Now, remember that I mentioned that there are  3 properties for the book objects, so I need  
00:03:15to express that in the diagram. I'll name this one "title".  
00:03:21This is a simple property, so I just  need to specify its type as a "string".  
00:03:26I'll right-click and choose Edit Properties. and I'll enter "string" for the type.  
00:03:36Remember that the 2nd property for book objects  is "genre". So, I'll drag a property component  
00:03:42and drop it below the title block. and I'll change this name to "genre". 
00:03:47Remember, the genre property is either a string  or an array of strings and this can easily be  
00:03:52expressed through the oneOf schema composition. Then I'll drop a definition component next  
00:03:58to the oneOf compositor. Once again I'll right-click  
00:04:02and select Edit Properties ... and I'll add a reference for this one.  
00:04:10The JSON validator signals that  the "genre" key is not found  
00:04:14but this will be corrected as I  continue to define the schema.  
00:04:18Then I'll put a definition component  below the block that was just created. 
00:04:22Remember that the 2nd possibility to express the  genre property is through an array of strings. 
00:04:28So, I'll change the type to "array" ...  
00:04:36and I'll put an items group  next to that same block. 
00:04:43and I'll edit the properties for the itemDef block  
00:04:46and add the same reference as I  just did a few minutes ago.  
00:04:50The genre property is now adequately defined,  but now I need to create the "genre" definition  
00:04:56in the "definitions" group. So, I'll put a  definition component below the book block.  
00:05:02and I'll name it genre. I can express the literary  
00:05:07genres as an enumeration of predefined strings,  so I'll add some strings for the enum property.  
00:05:16The 3rd property of the book object is authors  and it should be an array of author objects since  
00:05:21there could be multiple authors. So, I'll add  a property component below the genre block. 
00:05:27and I'll name it authors.  
00:05:30And I'll edit its properties and change the type  to array. THis implies an update of all properties  
00:05:36presented in the table, according to that type. and I'll change the value of the minItems  
00:05:43property to 1 so that at least  1 author must be included.  
00:05:48Then I'll put an items group  next to the author block. 
00:05:52I'll edit its properties.and add a reference for this one as well.  
00:06:00The validation error warns  me that I need to add the  
00:06:03"author" definition to the "definitions" group.  
00:06:09and I'll name it author. Notice the validation error is solved.  
00:06:16Now remember that the author property  contains the name and short_bio properties.  
00:06:22These 2 properties should be grouped  through a "properties" group.  
00:06:27Then I'll put a property component next to it. and I'll change the label to "name".  
00:06:35then I'll add another property  component below the name block.  
00:06:39and this one should be named "short_bio".  
00:06:45I'll edit it's properties. I'll  change the type to string ...  
00:06:52and I'll add some more restrictions.  Specifically that the short_bio  
00:06:56string must have at least 100  character but not more than 250.  
00:07:05Now I'll edit the properties for the name  block and change its type to string.  
00:07:14Now I want to make the name  property be "required",  
00:07:17so I'll right click and choose "Make Required".  
00:07:21Then I'll do the same for others.  
00:07:28Notice that when I make them be required, it  makes the connecting lines thicker to help  
00:07:33you to easily see which ones are required. Now I want to change the order of the properties  
00:07:40from the book as they appear in the diagram.  For example, I want the "authors" to be  
00:07:44after the "title" and to do this, I can  simply drag them to the new location.  
00:07:50You see that the order of the components changed  in the diagram and of course, that change is  
00:07:55also reflected in text mode. So now I have a  complete JSON schema to validate against.  
00:08:04I'll save my new schema file in the  same folder as the JSON file. 
00:08:14Now I need to associate the JSON schema document  that I just created to the library.json file.  
00:08:26Notice that the validator started automatically  and revealed an error. I'll click the Validation  
00:08:32button to inspect the errors. Note that Fiction is not a valid  
00:08:37value for the genre property so I'll  need to change it to a proper value.  
00:08:42I'll invoke the content completion assistant  by using Ctrl-Space and I'll choose "Drama".  
00:08:52The other error is because an empty  string for the short_bio is not accepted.  
00:08:56Remember that I imposed a string with a  minimum of 100 and a maximum of 250 characters.  
00:09:03This time I will hold down ctrl and  
00:09:07click short_bio with my mouse. This goes to its  definition where I can check the restrictions.  
00:09:16To solve this for now, I'll remove the short_bio  
00:09:19property since that wasn't one  that I made to be required.  
00:09:27And now, the JSON document is valid against  the JSON schema that we easily built  
00:09:32using the JSON schema Design mode  in conjustion with the Palette view.  
00:09:37This concludes the demonstration.  As always, thank you for watching.