Schemas

Define structure and validation rules for attestations

Schemas

A schema defines the structure and validation rules for credentials in the Solana Attestation System. Schemas serve as templates that specify what fields a credential should contain and how they should be formatted. Each schema is associated with a credential type and can be versioned to support evolution of the data structure.

Structure

The Schema struct represents a schema in the Solana Attestation System. Each schema defines a template for credentials that can be created under it.

Type Definitions

Schema

export type Schema = {
    discriminator: number;           // Internal discriminator
    credential: Address;             // Associated credential address
    name: ReadonlyUint8Array;       // Schema name
    description: ReadonlyUint8Array; // Schema description
    layout: ReadonlyUint8Array;     // Schema layout definition
    fieldNames: ReadonlyUint8Array; // Names of fields in the schema
    isPaused: boolean;              // Pause status
    version: number;                // Schema version
};

Methods

Fetching Schemas

Method	Description	Parameters	Returns
`fetchSchema`	Fetches a single schema by its address	`rpc`: RPC context, `address`: Schema's address, `config?`: Fetch config	`Promise<Account<Schema>>`
`fetchMaybeSchema`	Safely fetches a schema, returns null if not found	`rpc`: RPC context, `address`: Schema's address, `config?`: Fetch config	`Promise<MaybeAccount<Schema>>`
`fetchAllSchema`	Fetches multiple schemas by their addresses	`rpc`: RPC context, `addresses`: Array of schema addresses, `config?`: Fetch config	`Promise<Account<Schema>[]>`
`fetchAllMaybeSchema`	Safely fetches multiple schemas, skips not found	`rpc`: RPC context, `addresses`: Array of schema addresses, `config?`: Fetch config	`Promise<MaybeAccount<Schema>[]>`

Serialization

Method	Description	Parameters	Returns
`getSchemaEncoder`	Gets the encoder for schema data	None	`Encoder<SchemaArgs>`
`getSchemaDecoder`	Gets the decoder for schema data	None	`Decoder<Schema>`
`getSchemaCodec`	Gets the codec for schema data	None	`Codec<SchemaArgs, Schema>`

Usage Examples

Fetching a Single Schema

const schema = await fetchSchema(rpc, schemaAddress);
console.log('Schema name:', schema.name);

Fetching Multiple Schemas

const schemas = await fetchAllSchema(rpc, [schema1Address, schema2Address]);
schemas.forEach(schema => console.log('Schema:', schema.name));

Safe Fetching

const schema = await fetchMaybeSchema(rpc, schemaAddress);
if (schema) {
    console.log('Schema found:', schema.name);
} else {
    console.log('Schema not found');
}

Schema Layout Data Types

The layout field uses numeric values to specify data types for each field in the schema:

Value	Data Type	Description
0	U8	Unsigned 8-bit integer
1	U16	Unsigned 16-bit integer
2	U32	Unsigned 32-bit integer
3	U64	Unsigned 64-bit integer
4	U128	Unsigned 128-bit integer
5	I8	Signed 8-bit integer
6	I16	Signed 16-bit integer
7	I32	Signed 32-bit integer
8	I64	Signed 64-bit integer
9	I128	Signed 128-bit integer
10	Bool	Boolean value
11	Char	Single character
12	String	Variable-length string
13	VecU8	Vector of unsigned 8-bit integers
14	VecU16	Vector of unsigned 16-bit integers
15	VecU32	Vector of unsigned 32-bit integers
16	VecU64	Vector of unsigned 64-bit integers
17	VecU128	Vector of unsigned 128-bit integers
18	VecI8	Vector of signed 8-bit integers
19	VecI16	Vector of signed 16-bit integers
20	VecI32	Vector of signed 32-bit integers
21	VecI64	Vector of signed 64-bit integers
22	VecI128	Vector of signed 128-bit integers
23	VecBool	Vector of boolean values
24	VecChar	Vector of characters
25	VecString	Vector of strings

Example Usage

For example, a layout of [12, 0, 12] would define three fields: a String, followed by a U8 integer, followed by another String. The fieldNames array provides human-readable names that correspond positionally to each layout value, so with field names ["name", "age", "country"], the first String field would be named "name", the U8 field would be "age", and the second String field would be "country".

Here's an example of how those would be utilized when creating a Schema:

const createSchemaInstruction = getCreateSchemaInstruction({
    authority,
    payer,
    credential: credentialPda,
    schema: schemaPda,
    name: "Test Schema",
    description: "Just an example",
    fieldNames: ["name", "age", "country"],
    layout: Buffer.from([12, 0, 12]),
});

Important Notes

The discriminator field is used internally and should not be modified
The credential field links the schema to its associated credential type
isPaused can be used to temporarily disable schema usage
The version field allows for schema evolution while maintaining backward compatibility
layout and fieldNames define the structure of credentials using this schema
All byte array fields (name, description, layout, fieldNames) should be properly encoded/decoded according to your application's needs