Property Schema

At the heart of Custom Service Properties is the OpsLevel type system for defining strict property definitions. The type system allows you to define the exactly data you wish to represent on a service, using validation to ensure the information provided by service owners is correct. The type system may seem familiar because it leverages a large portion of JSONSchema, allowing for a wide variety of customization.

You can think of the Property Schema as a set of Property Definitions.

OpsLevel Metaschema

The OpsLevel Metaschema is a subset of JSONSchema, which can be leveraged in a wide variety of open source tooling. The full metaschema can be downloaded or referenced in tooling with https://app.opslevel.com/schemas/properties/v1/metaschema

Key differences between JSONSchema and the OpsLevel Metaschema include:

The use of an object at the root of the schema, requiring the key of type. While this is the typical format, JSONSchema also supports a wide variety of other schemas, including the use of booleans at the root of the schema. The OpsLevel Metaschema does not support other schema roots.
The type keyword does not support union types and must be either:
- single string value of: "string", "number", "boolean", "integer", "object" or "array"
```
{
	"type": "number"
}
```
- (to support nullable values) an array where one value is "null" and the other is one of the support types above. For more information on “null” usage, see the section below.
```
{
	"type": ["null", "boolean"]
}
```
While "array" is a supported type, it can only be used at the top-level of a property. The following schema is invalid:
```
{
  "type": "object",
	"properties": {
		"things": { "type": "array" }
	}
}
```

Common Examples

Dropdown (ENUM)

One of the most common use case for Custom Service Properties is for defining static, selectable values for a particular property. These properties will use validation to ensure a specific value is entered for the property, taking the form of a dropdown in the OpsLevel UI:

{
  "type": "string",
  "enum": [
    "Microservice",
    "Monolith",
    "Lambda"
  ]
}

Multi-Select (Array of ENUM)

Similar to Dropdown, Custom Service Properties support defining a list of static values to apply to the same property field. This allows a property to contain multiple values from the set of options, appearing as a multi-select in the OpsLevel UI:

{
  "type": "array",
  "items": {
    "type": "string",
    "enum": [
      "Internal Traffic",
      "External Traffic",
      "Public Traffic"
    ]
  },
  "minItems": 1,
  "uniqueItems": true
}

Date / DateTime

Using the type of string with the format keyword allows for validation of the entered value to conform to a specific date or datetime format, the ISO8601 format.

{
  "type": "string",
  "format": "date"
}

We also support a wide variety of different string formats, including: email addresses, IP addresses, URLs and regular expressions.

Nullable Values

The OpsLevel Metaschema supports the use of null as a valid assignment value, similar to JSONSchema. To specify null for a Property Definition you will need to define a slightly different type. Specifically when defining your type, you must include an array where 1 value is "null" and the other the datatype you wish to track.

{
	"type": ["null", "string"]
	"format": "date"
}

Most of the time there will not be a need to specify a null value for a Custom Service Property. By allowing and setting a Custom Service Property to null your service owner is indicating that they have fulfilled the requirement of setting a value (i.e. when using an exists Maturity Check) but there is no data to be stored. This is different than not assigning a value.

Nullable Enum

Enums require extra care when defining null values, due to how JSON Schema supports null. Below is a sample of a nullable enum:

{
	"type": ["null", "string"]
	"enum": ["Microservice", "Monolith", null]
}

Note: the type requires the use of "null" and the value of null must be an allowed value in enum options.