Data Validation Schema Definition

Last updated on August 24, 2021.

Document Status: Document Developer Quality Complete.

Introduction

This section describes JSON Schema and their properties.

Schema Definition

JSON Schema is a powerful tool for validating the structure of JSON data. JSON Schema are built around two core data structures: Objects and Arrays.

Object

A JSON object is a collection of properties inside a curly brace. The properties are key-value pairs where the key is always of type string and value can be any data type: string, boolean, or int.

{
    "Name" : "TestSchema",
    "IsList" : true 
}

Array

A JSON array is a list of objects inside a square bracket and separated by a comma.

[
    {
        "Name" : "TestSchema1",
        "IsList" : true 
    },
    {
        "Name" : "TestSchema2",
        "IsList" : false 
    }
]

Keywords

The following keywords are used in JSON Schema:

Keyword	Description
Name	Describes the name of the schema.
Type	Describes the object type.
Properties	Describes the key-value pairs of an object.
AvailableExtensions	Describes extensions that can be used with the schema.

Data Types

The following data types are used in JSON Schema:

Data Types	Description
System.String	This is enclosed in double quotes.
System.Int32	This is a non-fractional number ranging from 1 - 2147483647.
System.Boolean	This is true/false without quotes.

JSON Schema Example

A sample JSON Schema follows:

{
  "Name": "TestSchema",
  "Type": "TargetItem",
  "Properties": [
     {
      "Name": "MemoryMB",
      "Type": "System.Int32",
      "Attributes": [
        {
          "Name": "RequiredAttribute",
          "Values": {}
        },
        {
          "Name": "RangeAttribute",
          "Values": {
            "minimum": 1,
            "maximum": 2147483647
          }
        },
        {
          "Name": "DefaultValueAttribute",
          "Values": { "value": 2048 }
        }
      ]
    },
    {
      "Name": "BaseImage",
      "Type": "ResourceItem",
      "SchemaReference": "BaseImage",
      "NonValidationMetadata": {
        "DisplayName": "Base Image/Type"
      },
      "Attributes": [
        {
          "Name": "RequiredAttribute",
          "Values": {}
        }
      ]
    }
  ],
  "AvailableExtensions": [
    "IsDB",
    "IsCDN",
    "IsDC",
    "IsGUI",
    "IsProvisioningNic",
    "IsSync"
  ]
}

Getting to Know Properties

The following keywords are used when defining Properties:

Keyword	Description
Name	Describes the name of the property.
Type	Describes data types of the property.
SchemaReference	References the child schema.
Attributes	Describes validation attributes.
IsList	Describes whether the property is list or not.
NonValidationMetadata	Describes all the properties which do not require validation.

Warning

When adding a new property to the schema, the Name keyword cannot be set to a value of ExtraProperties. Example:

{
    "Name": "ExtraProperties",
    "Type": "System.String"
}

ExtraProperties is used internally by RPS as a Data Validation keyword. If ExtraProperties is used in a schema, validation errors will occur:

During item validation in REACTR.
During the creation of a new Target Item or Resource Item: when validating against the updated schema for the item type that contains the property name ExtraProperties.

Attributes

Attributes are used to validate the given property. There are four custom validation attributes implemented. They are described below:

1. ValidateDateTime Attribute

{
    "Name": "Date",
    "Type": "System.String",
    "Attributes": [
     {
        "Name": "ValidateDateTime",
        "Values": { }
     }
   ]
}

ValidateDateTime Attribute validates the property which requires Datetime value. Currently, this attribute supports two date-time formats:

MM/dd/yyyy
MM/dd/yyyy hh:mm tt

2. ValidateExpression Attribute

{
    "Name": "Role",
    "IsList": true,
    "Type": "System.String",
    "Attributes": [
     {
        "Name": "ValidateExpression",
        "Values": 
          {
            "expression": "$_ -Contains rpsadmin",
            "atLeast": 1
          }
     }
   ]
}

ValidateExpression Attribute validates the property by making sure the expression is true.

In this particular example, the expression is true if the name of the role contains rpsadmin. The value for the atLeast property is making sure the expression is true for at least 1 item in the list.

3. ValidateIpAddress Attribute

[
    {
      "Name": "IpAddressA",
      "Type": "System.String",
      "Attributes": [
         {
            "Name": "ValidateIpAddress",
            "Values": 
            {
                "LowerBoundIp": "10.0.0.0",
                "UpperBoundIp": "10.0.0.20"
            }
         }
      ]
    },
    {
        "Name": "IpAddressB",
        "Type": "System.String",
        "Attributes": [
         {
            "Name": "ValidateIpAddress",
            "Values": {}
         }
       ]
    }
]

ValidateIpAddress Attribute validates the property type of the IP Address. A custom IP range can be set by setting LowerBoundIp and UpperBoundIp.

Note

If no value is assigned for LowerBoundIp and UpperBoundIp, then the attribute will assign default values of 0.0.0.0 to LowerBoundIp and 255.255.255.255 to UpperBoundIp.

In this particular case, it is not required to explicitly declare in schema.

Alternatively, a Subnet can be provided in CIDR range instead of a LowerBoundIp and UpperBoundIp. This will calculate the LowerBoundIp and UpperBoundIp based on the provided Subnet.

[
    {
      "Name": "IpAddressA",
      "Type": "System.String",
      "Attributes": [
         {
            "Name": "ValidateIpAddress",
            "Values": 
            {
                "Subnet": "10.0.0.0/8"
            }
         }
      ]
    },
    {
        "Name": "IpAddressB",
        "Type": "System.String",
        "Attributes": [
         {
            "Name": "ValidateIpAddress",
            "Values": {}
         }
       ]
    }
]

In the example above, 10.0.0.0/8 would translate to a LowerBoundIp of 10.0.0.0 and UpperBoundIp of 10.255.255.255.

If neither a Subnet nor a LowerBoundIP and UpperBoundIP are assigned, the attribute will assign default values of 0.0.0.0 to LowerBoundIp and 255.255.255.255 to UpperBoundIp.

4. ValidateMacAddress Attribute

{
    "Name": "Date",
    "Type": "System.String",
    "Attributes": [
      {
        "Name": "ValidateMacAddress",
        "Values": { }
      }
   ]
}

ValidateMacAddress Attribute validates that the property type is a MAC Address.

For more information on additional attributes such as RequiredAttribute, RangeAttributes, and DefaultValueAttribute, refer to Microsoft docs link: https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations?view=net-5.0

Schema Reference

In the TestSchema below, we have a property with the Name "BaseImage". It has SchemaReference property with value "BaseImage". BaseImage is a schema with its own sets of all JSON data types and properties. TestSchema will inherit all the properties of BaseImage schema.

 {
    "Name": "BaseImage",
    "Type": ResourceItem,
    "SchemaReference": "BaseImage",
    "NonValidationMetadata": {
    "DisplayName": "Base Image/Type"
    },
    "Attributes": [
      {
          "Name": "RequiredAttribute",
          "Values": {}
      }
    ]
}

Create, Update and Delete the Schema

Currently, all schemas must be manually created, updated, and deleted.