00:00:06The purpose of this video is to present
some of the most commonly used features
00:00:10that are available when editing YAML
documents in Oxygen XML Editor.
00:00:16I'll start with a sample YAML document opened
in Oxygen. It contains data about a group of
00:00:21people. The first thing I want to highlight is the
YAML Outline view. It displays the node structure
00:00:28within the YAML document and the dependencies
between its components ... and notice that it
00:00:33is synchronized with the main editor, so
when I select something in the editor,
00:00:37the corresponding node is highlighted in
the Outline view ... and if I select a node
00:00:41in the Outline view, the corresponding
data is highlighted in the editor.
00:00:46The text filter at the top of
the Outline view can be used
00:00:49to focus on a particular subset of components.
00:00:56Note that YAML uses Python-style
indentation for nesting,
00:01:00and that's why you see all those "special"
dots at the beginning of the lines.
00:01:04These markers represent space characters that
YAML uses for indentation and really help you
00:01:09when editing YAML documents because
wrong indentation on a key causes the
00:01:13document to be not well formed.
Notice that the automatic validation
00:01:17presented the error in the editor,
as well as in the Outline view.
00:01:23I'll remove the extra space
to correct the error.
00:01:29Now I'll open a sample JSON schema
file that defines rules regarding
00:01:33the structure and possible values of
properties and keys in the YAML document.
00:01:38Oxygen uses associated schemas for both
validation and assisted content completion.
00:01:48I'll go back to the YAML document
and show you that there are 2 ways
00:01:52to associate a JSON Schema to a YAML document
in Oxygen. The first method is to configure
00:01:58a new validation scenario that binds
the schema to the YAML document.
00:02:03I'll click the settings icon to the right of the
validation unit to select my JSON schema file ...
00:02:10and I'll complete the process
to save the association.
00:02:18The 2nd method is to associate the schema
directly in the YAML document. In Oxygen,
00:02:24I can do this by clicking the "Associate schema"
toolbar button. Then I'll select the JSON schema,
00:02:29I'll enable the "Use path relative to the
file location" option, and click OK ...
00:02:36and you can see that the schema is now
referenced directly in the YAML document,
00:02:40in line 2. Note that if both methods are used
to associate a schema, then the schema specified
00:02:45in the validation scenario has a higher
priority and hence is the one that will
00:02:49be used by the validation engine.
Now that a schema is associated,
00:02:54I'll click the Validation button and you'll
notice there are a few errors reported.
00:02:59I'll click on the first error message in
the Results view that's reporting a non
00:03:03valid email address. I'll go ahead and fix it
... and that error is no longer reported.
00:03:09Now I'll click on the 2nd error that signals
there is a required "link" key that has no value.
00:03:15I'll right-click the link property
and select "Go to definition".
00:03:20This takes us to that particular
property's definition in the schema.
00:03:24Notice that there is a thick bold
line connecting it from the properties
00:03:28group component. This indicates that it is
required. I'll click the arrow at the end of
00:03:34the component to navigate to its definition
to continue to analyze the requirements.
00:03:40We can see that the "link" property should
contain "subordinates" or "manager" keys.
00:03:46Now I'll click the go to definition arrow
on one of those keys ... and the conclusion
00:03:52from the analysis is that "subordinates"
is defined as an array of String values,
00:03:56while "manager" is defined as a single
String value with up to 20 characters.
00:04:01So, now I'll go back to the YAML document
to correct the error. One major benefit
00:04:08of associating a schema to the YAML document is
that it provides the ability to use the content
00:04:14completion assistant that proposes the properties
that can be inserted at the current location.
00:04:20I'll place the cursor at the end of
the link construct, click Enter, add
00:04:252 blank spaces for the correct indentation ...
Then I'll use Ctrl + Space to trigger the content
00:04:31completion and I'll choose manager from the list
of proposals that are valid in this location.
00:04:39The errors and the Results view disappeared
and the document is now valid.
00:04:45Next, I'll demonstrate creating
a YAML file from scratch.
00:04:50I'll click the New file button on the toolbar ...
I'll find and select the YAML template ... I'll
00:04:58click "Customize" ... I'll select my JSON schema
... and in my case, I want all 3 of these options
00:05:06enabled ... and I'll click "Create" to
finish the document creation process.
00:05:13The resulting YAML file conforms with
the structure and the data restrictions
00:05:17expressed in the JSON schema I selected, and it
contains a "person" item in a "personnel" list.
00:05:24I could add more structure in the new
document using proper YAML indentation ...
00:05:32and the content completion assistant ...
00:05:36and I can edit any inserted default
values according to my needs ...
00:05:41and I could continue to add the
next property ... and so on.
00:05:49Conversions between YAML and JSON are often
necessary and Oxygen provides some very useful
00:05:55conversion tools that I will show you next.
First I'll convert a YAML document to JSON
00:06:02so I'll go to the Tools menu, then JSON Tools,
and I'll select "YAML to JSON". I'll select my
00:06:11YAML document for the input file, I'll leave the
output location as is, and click "Convert".
00:06:18I'll open the 2 files side
by side to compare them.
00:06:22The conversion mapping in this case is quite
straightforward, with small differences between
00:06:27the two based on the differences in the
language syntax of the 2 document types.
00:06:33Oxygen also includes a tool
for converting JSON to YAML.
00:06:46This type of conversion is very similar to
the other one, but in this case, you specify
00:06:51the URL of a JSON file for the input ... and
I'll change the name of the output file ...
00:07:04and it results in a converted YAML file.
00:07:09Those two conversion tools are for individual
files, but Oxygen also offers support for
00:07:15batch converting multiple files at once. To do
this, you need to install an additional Batch
00:07:20Converter add-on that provides numerous batch
conversion actions. More information about this
00:07:25add-on can be found in our user guide.
That concludes this demonstration of the
00:07:31YAML editing features included in Oxygen. Thank
you for watching. We welcome you to subscribe
00:07:37to our various social media channels and we
always welcome your feedback and suggestions.