Data Schemas

Emissary uses a subset of JSON-Schema to define and validate the custom data that is stored in each Theme, Template, and Widget.

Schemas validate all user-generated data two times. First: by the web UI to validate inputs before being sent, and second: by the server before saving any records to the database. This helps guarantee that malicious content cannot be injected into your web app.

Schema Highlights

Here is a sample snippet from a template schema:

	"schema": {
			"properties": {
					"token": {"type":"string", "required":true},
					"document": {"type":"object", "properties": {
							"label": {"type":"string"},
							"summary": {"type":"string"}
					"content":{"type":"object", "properties": {
							"type": {"type":"string"},
							"raw": {"type":"string"},
							"html": {"type":"string", "format":"html"}

Data Types


This data is not validated. Any information can be included here.



This data must be an array. The items in each array are defined as a sub-schema, with optional properties minlength and maxlength that set the bounds of the array.

{"type":"array", "items":{"type":"string"}, "minlength":0, "maxlength":10, "required":false}


This data must be a TRUE or FALSE. A default value can be set which will be used if no data is available.

{"type":"boolean", "default":true, "required":true}


This data must be a whole number. Optional properties default, minvalue, maxvalue, multipleof, and required* limit the values that are accepted.

{"type":"integer", "default":1, "minvalue":0, "maxvalue":42" "multipleof"2, "required":true}


This data must be a number with or without a decimal place. Internally, numbers are stored as a float64. It includes the same options as integer: default,minvalue, maxvalue, multipleof, and required*, but works with floats instead of ints.

{"type":"number", "default":1, "minvalue":0.1, "maxvalue":9.9", "multipleof":0.1, "required":false}


This data is stored as a Go map or struct, depending on the context. You can define sub-schemas for each of the properties within each Object, along with a list of required values that must be present in order for the Object to validate. All schemas in Emissary templates should have an Object at the top level.

{"type":"object", "properties":{ ... }, "required": ... }


This data must be a string value, although an optional format parameter can be used to validate the specific data within it. Optional properties minlength, maxlength, and required further validate the string.

{"type":"string". "format":"html"}

String Formats

Additional validators are included for guaranteeing that strings match a particular format. Some formats accept additional attributes, for example: the “lower” and “upper” formats allow you to specify a minimum number of lowercase or uppercase values. Multiple formats can be included in a single string schema by separating each one with a space. For example, you could use the following schema to define a common password rule that requires that a string have have a minimum of 12 characters, and must include at least one uppercase letter, one lowercase character, and one number:

{"type":"string", "format":"minlength=12 upper=1 lower=1 number=1"} requiring that all passwords .

Here are all of the formats that are available to string validators

Name Example Description
date "format":"date" PENDING
dateTime "format":"dateTime" PENDING
email "format":"email" Must be a valid email address (validated with built-in ParseAddress
hostname "format":"hostname" PENDING
html "format":"html" Valid HTML. values are filtered using the Blue Monday UGC Policy to remove potentially dangerous content
ipv4 "format":"ipv4" PENDING
ipv6 "format":"ipv6" PENDING
in "format":"in=one,two,three" Must be in the list of options provided
lower "format":"lower=6" Must contain a minimum number of lowercase letters
no-html "format":"no-html" Plain text without HTML tags. If no format is defined, this is the default.
notin "format":"notin=excluded,words" Must NOT contain any of the list of excluded words
number "format":"number=3" Must contain a minimum number of digits
objectId "format":"objectId" Must be a 24 character hexadecimal value
regex "format":"regex=abc123" Must conform to the specified Go Regexp
time "format":"time" PENDING
token "format":"token" Can only contain letters, digits, dashes, and underscores (case insensitive)
unsafe-any "format":"unsafe-any" Does not validate the string at all. MUST NOT BE USED FOR USER CONTENT
upper "format":"upper=6" Must contain a minimum number of uppercase characters
url "format":"url" PENDING