协议字符串Schema

• 协议字符串Schema
  • 图表格式
    • 类型
    • 外地
    • 同意字符串类型
    • 规格版本
    • 测试
    • 类型
    • 领域和部分
  • Schema 验证
    • 结构验证
    • 类型验证
    • 密钥验证

同意字符串将用户同意状态存储为二进制数据,编码为base64. 将用户同意状态编码为二进制字符串,或从已存在的字符串中解码,都需要一个编码器/解码器库. Schema以人可读的方式定义同意字符串格式. 这样可以定义出新的格式,或者对现有格式进行更新,而不修改编码器/解码器库.

图表格式

计划的结构如下:

• consent_string_type
• specification_version
• tests
• types
• fields 或者说 segments

类型

编码员和解码员需要知道他们合作的数据类型. 计划定义有特定类型的字段, 很像编程中的变量。 下列类型必须得到编码器/解码器库的支持:

外地

计划的主要组成部分是 field编辑 field 是一个编程语言中的变量的模拟,每个归档必须有一个类型. 有一个实地定义的例子:

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

在这里,我们正在定义的领域与 type "版本"和 key 等于“ dcs version” 。 编码器将使用 key 属性访问用户状态对象中提供的字段值。 我们还可以定义领域 value 属性指示编码器不从用户状态对象读取值,而是从计划读取值.

另一个例子是 field 属性是 optional。每个字段都可以是可选的,这将指示 编码器,在字段值之前将1比特旗放入编码字符串中. 如果旗帜是 1,该值是存在的并解码的。 如果是这样 0,在解码时,该值缺失并跳出. 有可选字段定义的例子

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

有些字段可以使用不同的编码算法进行编码来进行优化. 说明什么 算法(类型)可以通过编码器用于我们使用的值编码器 variants 字段属性 :

{

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

这个例子说明了如何使用三种方法来编码用户状态: bit_field_2_bits, (中文(简体) ), ranges_u16,以及 ranges_fibonacci。 。 。 . 编码器选择产生最短结果的方法并包含 在编码值之前选择方法的代码,允许解码器 以正确解码字符串.

有些类型需要有大小信息才能正确编码/解码.

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

我们在这里定义了一个12位字符串类型字段.

所有字段属性都有摘要:

同意字符串类型

同意字符串计划支持以下类型:

规格版本

对于每个字符串类型,可以定义几个规格版本,例如:, 给迪多米同意弦 specification_version 1和2,其中第1版 对编码器有一些限制.

测试

同意字符串计划定义了编码器和解码器的测试 tests 阵列。 编码器/解码器库应 运行这些测试,以确保库根据计划产生预期结果.

类型

这个 types 数组定义了由同意字符串计划支持的子集类型(类型) (中文(简体) ). 每个 type 从 types 必须至少出现在字段定义中,来自字段定义的所有类型都应该是 列入清单 types 阵列.

领域和部分

同意字符串计划可以 fields 顶级数组或 segments 阵列。 这个 fields 阵列包含字段定义( r)外地和 segments 能够 用于定义分块字符串结构,其中每个分块编码 单独连接,然后使用 . 字符键.

例如:

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

这里有一个 IAB TCF 字符串作为 encoded 值有两个部分:核心部分和出版部分.

在被定义为下列对象的图示中:

 {
    "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"
      }
    ]
  }

每个 segment 已经 name, (中文(简体) ), key, (中文(简体) ), optional 财务报告和审定财务报表 fields 属性,除 optional 强制的.

Schema 验证

同意字符串计划库提供 validator 函数,通过3个步骤验证计划:

• 使用 zod 图书馆
• 验证计划类型
• 验证密钥

结构验证

我们用 zod 以定义同意字符串结构以及控制类型。 比如说,有 field 使用定义 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()
});

这个计划确保了 type 属性只包含允许的类型 variants 属性包含三个允许的类型.

类型验证

虽然 zod 验证类型,计划还必须确保所有类型 types 阵列用于字段定义, 并且所有字段类型都列在 types 阵列。 此镜像编程语言, 其中类型被定义 使用前和未使用的定义可能触发警告或错误. 图书馆的 typeValidator 之后执行此约束 zod 审定.

密钥验证

最后的验证步骤需要确保域定义中的所有密钥都独一无二. 图书馆的 keyValidator 运行后 页:1 typeValidator 以强制执行这一限制.