Documentation

gitHub

Add a choice, conditional, or pattern field

In the previous tutorial, we reviewed how to create more complex structures with objects and arrays.  By the end of this tutorial, you will master the creation of other types of JSON Schema attributes: choices, conditionals, and pattern fields.

 

Note: some of the features in this tutorial are not available in all target technologies supported by Hackolade, in which case the feature is disabled.  

Choices

JSON Schema provides a way to combine schemas with the use of choice keywords:

  • allOf: the constraint must be valid against all of the subschemas (AND)
  • anyOf: the constraint must be valid against any of the subschemas (OR)
  • oneOf: the constraint must be valid against exactly one of the subschemas (XOR)
  • not: the constraint must not be valid against the subschema.

 

These keywords can be used to combine schemas together so a value can be validated against multiple criteria at the same time.  It can also be used in combination with references to assemble schemas from multiple files.

 

Put a different way, choices are a great way to implement polymorphism, in particular when complex data types are involved.  Hackolade fully supports the JSON Schema choices, making it much easier to visualize and maintain.

 

There are many different use cases for choices.  One that illustrates the capability is when a given field can be either a string or a complex subschema.  For example in e-commerce, a shipping address could be "same as billing", or it's own full address structure:

JSON Schema choices

 

To create a choice, simply right-click and choose to add, insert, or append a Choice, followed by the keyword adapted to you subschema validation criteria:

Tutorila - append a choice

 

The application automatically creates 2 subschemas which can be defined independently by adding child attributes:

Tutorial - choice subschemas

 

Additional subschemas can be added with teh right-click contextual menu.

 

 

Conditionals

Draft-07 of JSON Schema introduced the concept of conditional application of subschemas.  The if, then and else keywords allow the application of a subschema based on the outcome of another schema.

 

A misapplication of this feature is for multiple data types.  Multiple data types have been supported by earlier drafts of JSON Schema, whether for scalar/primitive data types, or when combining with complex data types through the use of choices.  It is also desirable to do so for backward-compatibility.

 

A better application of this feature is when having to allow the application of a subschema depending on the outcome of another schema:

  •  If if is valid, then then must also be valid (and else is ignored) 
  •  If if is invalid, then else must also be valid (and then is ignored)
  •  If then or else is not defined, if behaves as if they have a value of true
  •  If then and/or else appear in a schema without if, then then and else are ignored

 

 

Here is an example:

    "if": {

        "properties": {

            "country": {

                "type": "string",

                "const": "United States"

            }

        }

    },

    "then": {

        "properties": {

            "postal_code": {

                "type": "string",

                "pattern": "[0-9]{5}(-[0-9]{4})?"

            }

        }

    },

    "else": {

        "properties": {

            "postal_code": {

                "type": "string",

                "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]"

            }

        }

    }

 

which is represented in Hackolade:

JSON Schema conditional

 

 

To create a conditional structure, simply right-click and choose to add, insert, or append a Conditional.  

Tutorila - append a conditional

 

The application automatically creates conditional subschemas so you can define the constraints and expected outcomes::

Conditionals template

 

 

Pattern fields

Pattern fields function in exactly the same way as standard fields, with one exception: the name (in the name-value pair) is not a fixed string, but a regex pattern.

For example:

Pattern property example

This is represented in the Hackolade ERD as:

Pattern property ERD

The name in the name-value pair is not a fixed word, but a variable.  That's what pattern fields are for.  They are typically controlled by a regular expression, hence the name of pattern field.

You should not look at it as a 'field name', but as a key to a sub-document when embedding.  It lets you easily access the right sub-document inside an array or main document, using dot notation.

In Hackolade, the above example is modeled this way:

Pattern property schema

To add a pattern field to a document structure, right-click and choose add/insert/append > Pattern Field then the field data type:

Pattern property contextual menu

 

In this tutorial, we reviewed the creation of other types of JSON Schema attributes: choices, conditionals, and pattern fields.  In the next tutorial, we will cover how to add relationships to your entity-relationship diagram.