Custom Schema

Developers have the flexibility to create customized schema files tailored to their specific business needs, in addition to using the default schema. This enables them to fully leverage the capabilities of zkPass, ensuring seamless data verification from specified sources.

For instance, a developer from a decentralized web3 job recruitment platform might want users to verify:

  • Their work experience from Upwork

  • Their payroll statement from UOB bank

In order to achieve this, the developer can create two schemas utilizing the APIs provided by Upwork and UOB bank. To generate a valid schema, developers must adhere to the established schema standards.

Here is a typical schema example, demonstrating "Quora Account Owner":

{
  "issuer": "Quora",
  "desc": "The platform to ask questions and connect with people who contribute unique insights and quality answers.",
  "website": "https://www.quora.com/stats",
  "APIs": [
    {
      "host": "www.quora.com",
      "intercept": {
        "url": "graphql/gql_para_POST",
        "method": "POST",
        "query": [
          {
            "q": "UserStatsContentQuery",
            "verify": true
          }
        ]
      },
      "assert": [
        {
          "key": "data|viewer|__typename",
          "value": "Viewer",
          "operation": "="
        }
      ],
      "nullifier": "data|viewer|uid"
    }
  ],
  "HRCondition": [
    "Quora Account Owner"
  ],
  "tips": {
    "message": "When you successfully log in, please click the 'Start' button to initiate the verification process."
  }
}

Below is a detailed definition of the schema:

  • issuer: Name of data source, such as Twitter, Discord, etc.

  • desc: A detailed description of the schema.

  • website: Webpage link containing the specified APIs that return the data requiring verification. When a user initiates verification, the TransGate extension will display this page in the browser tab.

  • APIs: The RESTful APIs that return the specified data that needs to be verified. It is an array, meaning it can contain a series of APIs.

    • host: The host for the API.

    • intercept: Defines detail information of the API. The TransGate extension will perform 3P-TLS for the API that is defined here.

      • url: Absolute path for the URL of the API.

      • method: HTTP method for the API.

      • query: Refer to query parameters in the HTTP request header.

        • key and value: Specify the key and value for the query. For instance, in the URL https://...?needBalanceDetail=true, it should be defined as "needBalanceDetail": "true".

        • verify: If the key and value need to undergo zero-knowledge verification, the value should be true or false.

      • header: Refer to header parameters in the HTTP request header.

        • key and value: Specify the key and value for the header. For instance, header graphql-operation: AvatarMenuQuery, it should be defined as "graphql-operation": "AvatarMenuQuery".

        • verify: If the key and value need to undergo zero-knowledge verification, the value should be true or false.

      • body: Refer to body in the HTTP request.

        • key and value: Specify the key and value for the body.

        • verify: If the key and value need to undergo zero-knowledge verification, the value should be true or false.

    • assert: Defines the verification conditions.

      • key: Selector for the verified data field in JSON. Keys are separated by "|".

      • value: The value is used for comparison with the data associated with the key defined above.

      • operation: The assertion condition should be one of the following: >, <, =, >=, <=, !=, in, contains.

    • nullifier: Selector for the unique identifier field in JSON in the data source, such as uid, id, etc.

  • HRCondition: Descriptions for each assertion.

  • tips: User tips which is displayed in the bottom right corner of the data source website.

Developers can refer to existing schemas as a guide to create their customized schemas adhering to the established standards. After crafting the schema, developers can utilize the zkPass-Schema-Validator Chrome extension along with the data source website to validate it. Once successfully validated, developers can deploy the schema within the zkPass dev center for integration into their projects.

Last updated

Feel free to contact us if you have any ideas