Introduction

Piksel Palette is built on JSON as a lightweight data interchange format. It therefore aligns its data types with those of JSON, and provides additional data types as extensions of the JSON basic data types.

All fields have a field name and a value. A value may be of any type (scalar or compound), or the literal null. Typically, a schema is used to define fields and limit the allowed values for a given field through the use of types or to a specific set of allowed literal values (enumerated).

Scalar Data Types

Scalar data types hold a single unit of data.

Number

A number may be an integer or decimal value.

The following sub-types of number are also defined:

  • nonNegativeNumber - a decimal number greater than or equal to 0
  • integer - an integer
  • nonNegativeInteger - an integer greater than or equal to 0
  • positiveInteger - an integer greater than or equal to 1
  • percentage - a decimal number between 0.0 and 100.0 inclusive
  • perunit - a decimal number between 0.0 and 1.0 inclusive
  • year - a 4 digit integer between 1000 and 9999 inclusive

Boolean

A boolean may be either true or false.

String

A string is a sequence of one or more characters.

A string containing only whitespace characters is considered empty.

The following sub-types of string are also defined:

  • fieldName - one or more word characters, excluding underscore (i.e. [a-zA-Z0-9]+)
  • fieldNamePath - one or more field names separated by dot character
  • hex - one or more hex characters in lowercase (i.e. [a-f0-9]+)
  • uuid - a 36 characters UUID string in lowercase (i.e. [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})
  • password - a special type for passwords comprised of one or more characters
  • passwordDigest - a special type for password digests in the bcrypt format
  • version - a special type for the version fields comprised of 40 hex character sha1 hash
  • text - supports longer, potentially multi-line text

JsonPath

A jsonPath is an extension of a string and represents one or more values using dot notation.

The value must match the following regular expression: ([a-zA-Z0-9_-]+(?:\\[\\d+\\])?)+(?:\\.[a-zA-Z0-9_-]+(?:\\[\\d+\\])?)*.

Examples:

  • element
  • element.childElement[0]
  • element.childElement[0].grandchildElement
  • element[10]

Timestamp

A timestamp represents a date and time with accuracy to the nearest millisecond.

In data interchange representations (i.e. query parameters, headers and body) a timestamp is represented as a string and must be formatted as a ISO 8601 UTC timestamp to millisecond precision e.g. 2014-05-15T15:16:05.592Z.

Date

A date represents a day only (no time component) and is not timezone specific.

In data interchange representations (i.e. query parameters, headers and body) a date is represented as a string and must be formatted as a ISO 8601 date part only, e.g. 2014-05-15.

Duration

The duration type is used to specify a time interval. The time interval format follows ISO 8601 Duration and is tailored to the form “PnYnMnDTnHnMnS” where n is replaced by the value:

  • P indicates the period (required)
  • nY indicates the number of years
  • nM indicates the number of months
  • nD indicates the number of days
  • T indicates the start of a time section (required if you are going to specify hours, minutes, or seconds)
  • nH indicates the number of hours
  • nM indicates the number of minutes
  • nS indicates the number of seconds

Examples:

  • P1D (one day)
  • PT2H30M (two hours and thirty minutes)
  • P3Y2M1DT6H5M4S (three years, two months, one day, six hours, five minutes and four seconds)

Day Time Duration

A special case of duration used to specify a time interval using the following form “PnDTnHnMnS”

  • P indicates the period (required)
  • nD indicates the number of days
  • T indicates the start of a time section (required if you are going to specify hours, minutes, or seconds)
  • nH indicates the number of hours
  • nM indicates the number of minutes
  • nS indicates the number of seconds

Ip

Ip type is used to represent ipv4 address.

Id

An id is an extension of a string and represents an internal identifier that is specific to the datastore implementation.

A short ID of 24 lowercase hex characters. It may be a numeric incrementing value.

The value must match the following regular expression: [a-f0-9]{24}.

The length of an id is 24 characters for practical reasons due to indexing.

Examples:

  • 5374cc250f25c8524971ee50 (mongodb object id)
  • 341297854981549817547957
Id vs Name

It is recommended to associate resources through their name (i.e. friendly identifier) as this is controllable by the client and will be portable across environments and systems. e.g. root tenant name is reserved for each environment.

Name

A name is an extension of a string and represents a tenant specific friendly identifier that is under client control.

The value must match the following regular expression: [a-zA-Z0-9_-]+.

Normalisation

Because of the validation of a name type, it may be necessary to normalise any external identifiers.

NamePath

A name path is an extension of a string and represents one or more names separated by colon.

The value must match the following regular expression: [a-zA-Z0-9_-]+(:[a-zA-Z0-9_-]+)*.

Examples:

  • identity:user:read
  • identity:user:write
URN prefixes

If a name path starts with urn:{scheme}: then the scheme semantics must be understood. No urn:{scheme}: prefix is equivalent to a prefix of urn:piksel:.

Ref

A ref is an extension of a string and represents a global friendly identifier that is under client control. It composed of the tenant owner name and the resource name separated by a colon.

The value must match the following regular expression: [a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+.

The maximum length of a ref is 81 characters. This is for practical reasons due to indexing.

Examples:

  • root:root
  • test:5374cc250f25c8524971ee50
  • acme:game-of-thrones

MultiRef

A multiRef is an extension of a string and represents one or more refs separated by comma.

Examples:

  • acme:game-of-thrones
  • root:test,acme:game-of-thrones

Email

Special type for email address, validated using joi

Examples:

  • someone@example.com
  • john.smith@piksel.com

Fqun

Fully Qualified User Name is the domain and username separated by a backslash

domain\username

The domain is validated using the name type.

Example:

  • piksel\johnsmith (strict username policy)
  • acme\jane.smith@acme.com (email username policy)

URL

A URL which should in general meet the W3C URL spec. Relative or absolute varients, and those with or without a scheme are allowed.

Examples:

  • https://docs.sequoia.piksel.com/concepts/api/types.html
  • https://docs.sequoia.piksel.com/concepts/api/types.html#url
  • https://docs.sequoia.piksel.com/concepts/api/types.html?param=param%20value
  • docs.sequoia.piksel.com/concepts/
  • //docs.sequoia.piksel.com
  • /concepts/api/types.html
  • resourceful://demo.metadata/data/contents

Username

User Name

The username type is validated as .+

Example:

  • john.smith

Note: Users registered via business endpoints apply separate validation based on the username policy set in the directory

The strict usernamePolicy must match the pattern: ^[a-z_-][a-z0-9_-]{3,30}$

Example:

  • johnsmith
  • john_smith

The email usernamePolicy is validated as an email address using joi

Example:

  • jane.smith@acme.com

UserType

The type of user. Supported types are:

  • sysadmin
  • admin
  • service
  • enduser

Protection Scheme

The Protection Scheme to be applied, must be one of PLAYREADY, WIDEVINE or FAIRPLAY

MIME

Media Type (formerly MIME) consists of a type and a subtype, which is further structured into a tree which is following this pattern [a-z]+(-[a-z]+)*/[a-z0-9]+([-.+][a-z0-9]+)*

Examples of valid mime values:

  • text/plain
  • application/octet-stream
  • multipart/form-data
  • image/svg+xml
  • audio/x-pn-wav
  • application/vnd.amazon.ebook
  • application/vnd.oasis.opendocument.spreadsheet

Compound Data Types

Compound data types are comprised of multiple scalars or compounds.

Map

A map is an unordered set of name/value pairs, limiting the values to only string, number, boolean, timestamp or arrays thereof.

StringMap

A stringMap is an unordered set of name/value pairs being name a fieldName string sub-type and allowing any character within value part.

FieldNamePathMap

FieldNamePathMap is an unordered set of key/value pairs. The key must be a valid string of the fieldNamePath sub-type. The value can be any string or a set of allowed values if provided.

Array

An array is an ordered collection of values.

An array having no values is considered empty.

Language

Language is subset of BCP-47 compliant strings limited to the primary language and region subtags only (e.g. en, en-US etc.)

Currency

A string where the possible values are 3 letter codes conforming to ISO 4217 currency codes, limited to CHF, CLP, EUR, GBP, USD

Money / Price

Money is a special case of a map type where the key is a currency code and the value is a number.

Ratings

Ratings is a special case of a map type where its key/values are a schema:level pair. Supported schemes are:

  • BBFC - Uc, U, PG, 12A, 12, 15, 18, R18
  • FPB - A, PG, 7-9-PG, 10-12-PG, 13, 16, 18, X18, XX
  • MPAA - G, PG, PG-13, R, NC-17
  • TVPG - TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA
  • ESRB - RP, EC, E, E10+, T, M, AO
  • PEGI - 3, 7, 12, 16, 18
  • FSK - FSK 0, FSK 6, FSK 12, FSK 16, FSK 18
  • KIJKWIJZER - AL, 6, 9, 12, 16

Scores

Scores is a special case of a map type where the key is a fieldNamePath and the value is a number.

LIVR Spec

livrSpec is a type that will be used mainly by validation-service, which is used for validating data structures in a declarative way, and independent from the language. Example of this type, could be something like this:

{
    title: ['required', {'max_length': 20}],
    ref:  { like:"[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+" },
    type: [
      "required",
      {
        one_of: ["application", "audio", "image", "text", "video", "other"]
      },
      "not_empty"
    ]
}

Structure of the validation rules, more examples, and other info can be found in the official site http://livr-spec.org/.

Schedule

The schedule type is used to specify a recurring event. It’s defined as an iCalendar RFC recurrence rule followed by ISO 8601 Duration, separated by #

For generation of the rrule, see the implementation at https://www.npmjs.com/package/rrule

Examples:

  • DTSTART:20120201T093000Z\nRRULE:FREQ=MONTHLY;INTERVAL=5#P1D (1 day event occuring every 5 months, starting at 2012-02-01 09:30)
  • RRULE:FREQ=MONTHLY;COUNT=5#PT20M (5 events lasting 20 minutes occuring every month, starting now)