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 withx-data-classification:
Values are lowercase and case-sensitive.
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
propertiesnoritems, and under draft 2020-12 noprefixItems. 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
itemswhen 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 withoutitems(and under draft 2020-12 withoutprefixItems), is a leaf, and its whole value takes the class. Use this for a map whose keys you don’t know in advance. - Along
propertiesand single-schemaitemsonly. The annotated leaf must be reached from the root throughpropertiesanditems, or be the root itself. Schemas under$ref,$defs,oneOf,anyOf,allOf,not,if,then,else,prefixItems,patternPropertiesoradditionalPropertiescan’t carry an annotation. Without one they are allowed, and their leaves areany. - Not on a draft-07 tuple. Under draft-07,
itemsgiven 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: falseon 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 a422 validation error on schema when the schema:
- uses an annotation value other than
anyorpii, including a differently cased one such asPII; - uses
pci-panorpci-sad, which generic tokens don’t support yet; - puts an annotation on a schema that isn’t a leaf, or anywhere other than along
propertiesand single-schemaitems.
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.