Names and Schemas

A POD is a cryptographic record with no enforced schema. A POD is made up of entries consisting of a name (always a string) and a value (of a supported type). Values are scalars with no nested objects, meaning the POD structure is flat.

Apps can represent their data however they like. Entry names and values are hashed and cryptographically verified in a POD. The issuer of a POD decides what the expected set of names and values should be for their use case. The definition order of entries is not important since entries area always sorted by name before hashing.

• Names: The cryptography behind PODs will accept any name or value which can be validly hashed. The POD library enforces the legal characters in names described below.
• Value schemas: There is no formal notion of a schema for POD entries, but there are some recommended best-practices apps should follow, most particularly the use of the pod_type and Zupass Display entries described below.

The rest of this page describes the requirements and recommendations about POD names and schemas.

Legal Names

POD names (represented by the PODName type) are limited to a character set which matches variable identifiers in most languages. They allow alphanumeric characters and underscores, and cannot begin with a digit. This allows PODEntries to be conveniently accessed as TypeScript objects without quoting their names:

const idEntries = idPOD.asEntries();
if (idEntries.pod_type === "zu_gov.id") {
  const user = findUser(idEntries.idNumber);
  // ...
}

Security and Future Proofing

While the legal characters are checked by the SDK, they are not cryptographically enforced. Custom code can sign a POD with any string in its names. Thus if your app will be consuming data in unknown formats, you shouldn’t assume that a POD name won’t contain special characters beyond those defined here. E.g. if a POD name comes from untrusted input, you shouldn’t assume it won’t contain special characters used for SQL injection.

This limited character set is restrictive today, but may expand in future versions to support new features. This also leaves special characters to be used for special purposes outside of PODs themselves, such as in GPC proof configuration (see below).

Use of Names in GPCs

The PODName specification is also used in GPC configuration when a name is needed to refer to a whole POD, or a list of values, etc. These names follow the same PODName rules for convenience, but this detail is not cryptographically relevant. These names exist only for the GPC compiler to correlate different parts of the config and inputs, and do not appear in the ZK circuit.

Name Order

The GPC compiler uses lexicographic order to sort multiple PODs or entries before asigning the modules in a circuit. Thus while the extended names in config are arbitrary and could be changed, it is important that prover and verifier at least agree on their order.

The GPC compiler also uses some special characters when naming things in constraints, for example:

• idPOD.idNumber names a POD and an entry of that POD. In this case idPOD is an arbitrary name assigned to a POD, while idNumber is the name of an entry which must be in the POD.
• idPOD.$signerPublicKey names the public key of a POD. The name $signerPublicKey never appears in the POD itself, but the config compiler treats it as a virtual entry when defining constraints.

Reserved Names

Apps should avoid defining their own entry names with the prefixes pod_ or zupass_ as these are reserved for special uses in the SDK, or in Zupass. Some of these have defined uses described below, which apps are encouraged to use accordingly. Remaining names with those prefixes are reserved for future use.

pod_type

The pod_type entry is the a recommended way for apps to tag their PODs to let their contents be understood across apps. It should be used by apps to identify the purpose or schema of their PODs using some unique identifier. In future, this might be used to index into a library of published schema identifiers. For now, the pod_type is not enforced, but is helpful to avoid mixing PODs with common names. For instance, pod.name means something different on a driver’s license than it does on a collectible frog.

There is no required format for pod_type, but it is recommended to contain the name or identifier of your app so as to be unique. Reverse domain name notation is a good way to ensure that.

pod_type Security

The pod_type is a good way to avoid accidental misuse, but is usually only the second step in trusting the meaning of a POD. The first step should always be to check that the POD is signed, and almost always to check that its public key is a trusted signer. A known signer might be trusted to follow a schema, making pod_type redundant (but still recommended) for signers which issue only one type of POD. An untrusted signer could sign anything, so if your app accepts data from any signer (e.g. user-signed PODs) be sure to check its validity like any untrusted input.

Zupass Display

Zupass is a generic POD store able to hold any type of POD, and show the user its entries. It’s easier for a user if that POD can display in a friendlier format than a JSON dump. If you anticipate your POD being stored in Zupass, you should set one or more of the following fields:

• zupass_display (string): the preferred display format for your POD. Accepted values are:
  • collectable displays the other fields described below in a card. Requires at least one of title, description, or image URL to be set.
  • pod explicitly chooses the default JSON display
• zupass_title (string): a short title for your POD, used in folder listings and/or the top of the display card.
• zupass_description (string): a text description of your POD
• zupass_image_url (string): the URL to fetch an embedded image to display with your POD.

Images

Any URL suitable for an <image> tag should work in zupass_image_url. Be careful to select an image URL which will remain available, to avoid broken image links when users save their PODs into the future. You can also use a data: URL for embedded images, though this is suitable only for small icons. Zupass enforces a maximum size for PODs, currently at 10KB.

Outside of Zupass, how you display your PODs is entirely up to you. You can use the JSON format defined by pod.toJSON() which is intended to be human-readable, but you can also invent your own formats more specific to your app.

Suggested Best Practices

Here are some remaining suggestions about naming and using POD entries, which don’t depend on reserved characters or names.

Ownership

PODs can be marked with a user’s identity in a way which allows a GPC to prove ownership. There is no fixed entry name for this purpose, since it can be selected in the GPC configuration. Thus you could name your ownership entry attendee or citizen as befits your use case. However if you want a recommended default, you can use an entry named owner of type eddsa_pubkey.

Example POD

Here is an example POD which follows all the requirements and best-practices described in this page. This is the Meerkat app’s proof of attendance from a talk at Devcon 7 SEA.

{
  "entries": {
    "code": "MQ8T8Z",
    "conference": "Devcon SEA",
    "end_date": {
      "date": "2024-11-12T08:30:00.000Z"
    },
    "owner": {
      "eddsa_pubkey": "DVZ1idpAigmvfwYem2pvbHNPp7IAia0ER98dwxVrd5M"
    },
    "pod_type": "events.meerkat/attendance",
    "start_date": {
      "date": "2024-11-12T08:00:00.000Z"
    },
    "track": "Applied Cryptography",
    "version": "1.0.0",
    "zupass_description": "Programmable Cryptography is a \"second generation\" of cryptographic primitives - primitives that allow arbitrary programs to be executed \"inside of\" or \"on top of\" cryptographic objects. Programmable cryptography provides three key affordances that complement and amplify the affordances of Ethereum--verifiability, confidentiality, and non-interactivity. We'll discuss how these technologies can reshape the Internet over the next 50 years.",
    "zupass_display": "collectable",
    "zupass_image_url": "https://icnyvghgspgzemdudsrd.supabase.co/storage/v1/object/public/images/owl_Applied%20Cryptography.png?t=2024-10-31T11%3A20%3A31.354Z",
    "zupass_title": "Keynote: Programmable Cryptography and Ethereum"
  },
  "signature": "k7NpiGbrSZJRivZ5D4RXQTFs2w+EsFjeYiFuxUloY56AryxzeQdAh6yUtABhw1r8EElx9no59gKrD+htlRqFAQ",
  "signerPublicKey": "XfAQCwo2k69LAW1gRLUs1qsnQ2rVJ6VaF3yotol5HQ4"
}