Skip to main content
Types define schemas for generic token payloads. They enable validation and filtering for generic tokens and provide structure for otherwise flexible payloads.

Overview

Types are schema definitions that can be applied to Generic Tokens. They describe the expected structure of the payload and are enforced when generic tokens are created or updated.

Key features

  • Schema definition: Define the structure of generic token payloads.
  • Validation: Ensure payloads match the defined schema.
  • Filtering: Query generic tokens based on schema-defined fields.
  • Type safety: Enforce consistent data structures across tokens.

Example use cases

  • SEPA credential schemas.
  • API key metadata structures.
  • Custom authentication token formats.
  • Any structured sensitive data that benefits from validation and filtering.

Schema dialect

A type’s schema is JSON Schema draft 2020-12, the default when $schema is absent, or draft-07 when $schema names http://json-schema.org/draft-07/schema, with or without a trailing #. A schema that names any other $schema, or isn’t a valid schema of its dialect, is refused with a 422 on schema: must be a valid JSON schema.

Data classification

A type’s JSON Schema can declare which payload values are personal data. Annotate a leaf schema with x-data-classification: Values are lowercase and case-sensitive.
Here holder_name, every element of emails and the whole value of profile are pii. customer_ref is any.

Where an annotation can sit

  • Only on a leaf schema, one with neither properties nor items, and under draft 2020-12 no prefixItems. To classify the values of an object or an array, annotate the leaf schemas inside it. Nothing is inherited from a schema above a leaf.
  • On an array’s items when it is a single schema and a leaf. Every element takes its class.
  • On a free-form object or array. An object without properties, or an array without items (and under draft 2020-12 without prefixItems), is a leaf, and its whole value takes the class. Use this for a map whose keys you don’t know in advance.
  • Along properties and single-schema items only. The annotated leaf must be reached from the root through properties and items, or be the root itself. Schemas under $ref, $defs, oneOf, anyOf, allOf, not, if, then, else, prefixItems, patternProperties or additionalProperties can’t carry an annotation. Without one they are allowed, and their leaves are any.
  • Not on a draft-07 tuple. Under draft-07, items given as a list is the tuple form. An annotation on that array or inside one of its positions is refused.

Values that stay any

  • A leaf without an annotation.
  • A key the schema doesn’t declare, wherever it sits, even under a declared object. Set additionalProperties: false on an object to refuse keys it doesn’t declare.
  • Every leaf of a generic token created without a type or an inline schema.

Refused schemas

Creating a type returns a 422 validation error on schema when the schema:
  • uses an annotation value other than any or pii, including a differently cased one such as PII;
  • uses pci-pan or pci-sad, which generic tokens don’t support yet;
  • puts an annotation on a schema that isn’t a leaf, or anywhere other than along properties and single-schema items.
Each message names the location in the schema as a JSON Pointer, and never repeats a value from the schema:
Types created before these checks existed aren’t checked again and keep working. The exception is a stored schema that holds an annotation these rules refuse: creating a token against that type returns a 422 on type_id.

Sample values

example, examples and default are allowed anywhere in a schema, as are const and enum. Guardian keeps their values as written and never reads them as schemas, so an x-data-classification key inside an example value classifies nothing.

Reading a type

A type read returns its schema as you wrote it, annotations included. Guardian doesn’t trim whitespace in schema strings. Key order may differ from the order you sent.