Consent String Schema

• Consent String Schema
  • Schema format
    • Type
    • Field
    • Consent String Type
    • Specification Version
    • Test
    • Types
    • Fields and segments
  • Schema Validation
    • Structure validation
    • Type validation
    • Key validation

Consent strings store user consent status as binary data, encoded in base64. Encoding user consent status into a binary string, or decoding it from an existing one, requires an encoder/decoder library. The schema defines the consent string format in a human-readable way. This allows new formats to be defined, or existing ones updated, without modifying the encoder/decoder library.

Schema format

The schema has the following structure:

• consent_string_type
• specification_version
• tests
• types
• fields or segments

Type

Encoders and decoders need to know the type of data they're working with. The schema defines fields with specific types, much like variables in programming. The following types must be supported by the encoder/decoder library:

| # | type id | description | |----|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | u1 | Unsigned integer number of 1 bit size (0 or 1) | | 2 | u2 | Unsigned integer number of 2 bits size | | 3 | u3 | Unsigned integer number of 3 bits size | | 4 | u4 | Unsigned integer number of 4 bits size | | 5 | u6 | Unsigned integer number of 6 bits size | | 6 | u12 | Unsigned integer number of 12 bits size | | 7 | u16 | Unsigned integer number of 16 bits size | | 8 | u24 | Unsigned integer number of 24 bits size | | 9 | u32 | Unsigned integer number of 32 bits size | | 10 | date | Date | | 11 | uuid | User ID - Base16 string xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' | | 12 | fibonacci | Fibonacci Number | | 13 | fibonacci_range | Fibonacci range of ids with start_id and number_of_ids in Fibonacci numbers | | 14 | u16_range | Ids range with start_id and end_id as u16 numbers | | 15 | bit_field | Array of bits | | 16 | fixed_bit_field | Fixed Size BitField array, size property must be specified in the schema | | 17 | bit_field_2_bits | BitField array of tuples (bool, bool) | | 18 | ranges_u16 | Array of id ranges - (start_id: u16, end_id: u16) | | 19 | ranges_fibonacci | Array of id ranges - (start_id: fibonacci, number_of_ids: fibonacci) | | 20 | string | A fixed amount of bit representing a string. The character’s ASCII integer ID is subtracted by 65 and encoded into an int(6). | | 21 | optimized_range | First data type is always a Boolean (u1) and if it is true then the next is Fibonacci range, if false - Bitfield. | | 22 | optimized_u16_range | Optimized BitField with u16_range - (max_id: u12, range_flag: u1, type: [u16_range, fixed_bit_field(size: max_id)]) | | 23 | array_of_optimized_u16_ranges | Array of optimized_u16_range (number_of_records: u12, key: u6, type: u2, ids: optimized_u16_range) | | 24 | n_array_of_ranges_x_y | Generic type<X,Y> (number_of_records: u12, key: u, type: u, ids: optimized_range) | | 25 | optimized_array_of_u16_ranges | (max_id: u16, is_range_encoding: u1, type: [(number_of_entries: u12, is_a_range: u1, type: [(start_id:u16, end_id: u16), start_id:u16]), fixed_bit_field(size: max_id)]) | | 26 | array_of_u16_ranges | (number_of_records: u12, key: u6, type: u2, number_of_entries: u12, is_a_range: u1, type: [(start_id:u16, end_id: u16), start_id:u16]) | | 27 | segment_type | The 3bits code of segment type | | 28 | enabled_disabled_ids | The enabled and disables ids encoded with some types listed in variants property | | 29 | array_of_attributed_u16_ranges | The array of attributed ranges used for publisher restriction encoding | | 30 | version | The consent string version encoded in 6bits number |

Field

The main building block of the schema is a field. The field is analog of variable in a programming language and each filed must have a type. There is a field definition example:

{
  "type": "version",
  "description": "The Didomi Consent String version 6bits number",
  "key": "dcs_version",
  "value": 2  
}

Here we are defining the field with type "version" and key equal to "dcs_version". The encoder will use the key property to access the field value provided in the user status object. We could also define the field value property to instruct the encoder to read the value not from the user status object but from the schema.

Another example of the field property is optional. Each field could be an optional and this will instruct encoder to place 1 bit flag in encoded string before the field value. If the flag is 1, the value is present and decoded. If it's 0, the value is absent and skipped during decoding. There is example of the optional field definition

{
  "type": "date",
  "key": "sync",
  "optional": true
}

There are fields that could be encoded using different encoding algorithms for optimization purposes. To specify what algorithms (types) could be used by encoder for value encoder we use variants field attribute:

{

  "type": "enabled_disabled_ids",
  "description": "User Status for purposes opt-out",
  "key": "purposes_li",
  "variants": [
    "bit_field_2_bits",
    "ranges_u16",
    "ranges_fibonacci"
  ]
}

This example shows how to encode user status for purposes using three methods: bit_field_2_bits, ranges_u16, and ranges_fibonacci. The encoder chooses the method producing the shortest result and includes the chosen method's code before the encoded value, allowing the decoder to correctly decode the string.

Some types need to have size information to encode / decode correctly.

{
  "type": "string",
  "description": "Two-letter ISO 639-1 language code in which the CMP UI was presented",
  "key": "consent_language",
  "size": 12
}

Here we are defining a 12 bits string type field.

There is the summary for all field attributes:

| # | field attribute | mandatory | description | |---|-----------------|-----------|-------------------------------------| | 1 | type | Y | field type | | 2 | key | Y | key to extract value from the model | | 3 | description | Y | field description | | 4 | size | N | type size bits | | 5 | optional | N | true if value could be missing | | 6 | value | N | field constant value | | 7 | variants | N | type encoding methods variants |

Consent String Type

The consent string schema supports the following types:

| # | string type | description | |---|-------------------------|------------------------| | 1 | didomi_consent_string | Didomi Consent String | | 2 | iab_tcf_string | IAB TCF Consent String | | 3 | gpp_string | GPP String |

Specification Version

For each string type several specification versions could be defined, for example, for Didomi Consent String we have specification_version 1 and 2, where version 1 has some restrictions for the encoder.

Test

The consent string schema defines tests for an encoder and decoder in tests array. The encoder/decoder library should run these tests to make sure the library produces expected results based on the schema.

Types

The types array defines a subset of types supported by the consent string schema (Type). Each type from types must appear at least ones in field definition and all types from fields definition should be listed in types array.

Fields and segments

The consent string schema could have fields array on the top level or segments array. The fields array contains field definition (Field) and segments could be used to define a segmented string structure, where each segment encoded separately and then connected to each other using . character.

For example:

{
  "tests": {
    "encoded": "CQH-gkAQH-gkAAHABBENBOFgAPAAAELAAAAAF5wAQF5gXnABAXmAAAAA.YAAAAAAAAAAA"
  }
}

Here we have an IAB TCF string as encoded value with two segments : core and publisher.

In the schema segments defined as the following object:

 {
    "name": "Disclosed Vendors",
    "key": "disclosed_vendors",
    "optional": true,
    "fields": [
      {
        "type": "segment_type",
        "description": "DisclosedVendors segment is 1 which is 001 in binary.",
        "key": "disclosed_vendors_segment_type",
        "value": 1
      },
      {
        "type": "optimized_array_of_u16_ranges",
        "description": "Vendors Disclosure",
        "key": "disclosed_vendors"
      }
    ]
  }

Each segment has name, key, optional and fields properties, where the all property except optional mandatory ones.

Schema Validation

The consent string schema library provides validator function that validates schemas using 3 steps:

• validate schema structure using zod library
• validate schema types
• validate schema keys

Structure validation

We use zod to define the consent string schema structure and also control types. For example, there is field definition using zod:

import { z } from 'zod';

export const availableTypesSchema = z.nativeEnum(SchemaTypes);

export const typesSchema = uniqueNotEmptyArray(availableTypesSchema);

export const consentStringTypeSchema = z.enum([
  'didomi_consent_string',
  'iab_tcf_string',
  'gpp_string',
]);

export const variantsTypes = z.enum([SchemaTypes.bit_field_2_bits, SchemaTypes.ranges_fibonacci, SchemaTypes.ranges_u16]);

export const variantsSchema = uniqueNotEmptyArray(variantsTypes);

export const fieldSchema = z.object({
  type: availableTypesSchema,
  description: z.string(),
  key: z.string(),
  optional: z.boolean().optional(),
  size: z.number().or(z.string()).optional(),
  value: z.number().optional(),
  variants: variantsSchema.optional()
});

This schema ensures the type property contains only permitted types, and the variants property contains exactly three allowed types.

Type validation

While zod validates types, the schema must also ensure all types in its types array are used in field definitions, and that all field types are listed in the types array. This mirrors programming languages, where types are defined before use and unused definitions may trigger warnings or errors. The library's typeValidator enforces this constraint after zod validation.

Key validation

The last validation step need to ensure that all keys in the fields definition unique. The library's keyValidator runs after the typeValidator to enforces this constraint.