Vana SDK - v2.2.2
    Preparing search index...

    Class SchemaController

    Manages data schemas for validation and structure definition on Vana.

    Handles schema lifecycle from creation through registration. Schemas define data structure and validation rules, ensuring consistency across the network. Stored unencrypted on IPFS for public reusability.

    Architecture: Schemas use dual storage: definitions on IPFS (public), metadata on blockchain. Supports JSON Schema and SQLite dialects for flexible data modeling.

    Method Selection:

    • create() - Validate, upload to IPFS, register on blockchain
    • get() - Retrieve schema with definition by ID
    • list() - Paginated schema browsing with metadata
    • count() - Total schemas for pagination
    • addSchema() - Low-level registration with pre-uploaded URL

    Storage Requirements:

    • Methods requiring storage: create()
    • Methods without storage: get(), list(), count(), addSchema()
    // Create schema with validation rules
    const result = await vana.schemas.create({
      name: "User Profile",
      dialect: "json",
      schema: {
        type: "object",
        properties: {
          name: { type: "string", minLength: 1 },
          age: { type: "number", minimum: 0, maximum: 150 }
        },
        required: ["name"]
      }
    });
    console.log(`Schema ${result.schemaId} created`);

    // Retrieve for validation
    const schema = await vana.schemas.get(result.schemaId);
    console.log(`Schema: ${schema.name} (${schema.dialect})`);

    // Browse available schemas
    const schemas = await vana.schemas.list({ limit: 10 });
    schemas.forEach(s => console.log(`${s.id}: ${s.name}`));

    For conceptual overview, visit https://docs.vana.org/docs/schemas

    Hierarchy

    • BaseController
      • SchemaController
    Index

    Methods

    create get count list retrieveDefinition retrieveRefinementInstructions addSchema

    Methods

    • Creates a schema with validation and IPFS upload.

      Parameters

      • params: CreateSchemaParams

        Creation configuration

        Parameters for creating a new schema with automatic IPFS upload.

        • name: string

          The name of the schema

        • dialect: "json" | "sqlite"

          The dialect of the schema (e.g., 'json' or 'sqlite')

        • schema: string | object

          The schema definition object or JSON string

      Returns Promise<CreateSchemaResult>

      Schema ID, IPFS URL, and transaction hash

      Primary method for schema creation. Validates definition, uploads to IPFS (unencrypted for reusability), and registers on blockchain. Schema becomes immediately available network-wide.

      Invalid schema definition. Verify schema follows JSON Schema or SQLite format.

      Storage not configured. Configure storage providers in VanaConfig.

      IPFS upload failed. Check network and storage provider status.

      const result = await vana.schemas.create({
        name: "User Profile",
        dialect: "json",
        schema: {
          type: "object",
          properties: {
            name: { type: "string", minLength: 1 },
            age: { type: "number", minimum: 0 }
          },
          required: ["name"]
        }
      });
      console.log(`Schema ${result.schemaId} at ${result.definitionUrl}`);

    • Retrieves a complete schema by its ID with definition fetched and flattened.

      Parameters

      • schemaId: number

        The ID of the schema to retrieve

      • options: { subgraphUrl?: string } = {}

        Optional parameters

        • OptionalsubgraphUrl?: string

          Custom subgraph URL to use instead of default

      Returns Promise<CompleteSchema>

      Promise resolving to the complete schema object with all fields populated

      When the schema is not found, definition cannot be fetched, or chain is unavailable

      const schema = await vana.schemas.get(1);
      console.log(`Schema: ${schema.name} (${schema.dialect})`);
      console.log(`Version: ${schema.version}`);
      console.log(`Description: ${schema.description}`);
      console.log('Schema:', schema.schema);

      // Use directly with validator (schema has all required fields)
      validator.validateDataAgainstSchema(data, schema);

    • Gets the total number of schemas registered on the network.

      Parameters

      • options: { subgraphUrl?: string } = {}

        Optional parameters

        • OptionalsubgraphUrl?: string

          Custom subgraph URL to use instead of default

      Returns Promise<number>

      Promise resolving to the total schema count

      When the count cannot be retrieved

      const count = await vana.schemas.count();
      console.log(`Total schemas: ${count}`);

      // With custom subgraph
      const count = await vana.schemas.count({
        subgraphUrl: 'https://custom-subgraph.com/graphql'
      });

    • Lists all schemas with pagination.

      Parameters

      • options: {
            limit?: number;
            offset?: number;
            subgraphUrl?: string;
            includeDefinitions?: boolean;
            minBlock?: number;
            waitForSync?: number;
        } = {}

        Optional parameters for listing schemas

        • Optionallimit?: number

          Maximum number of schemas to return

        • Optionaloffset?: number

          Number of schemas to skip

        • OptionalsubgraphUrl?: string

          Custom subgraph URL to use instead of default

        • OptionalincludeDefinitions?: boolean

          Whether to fetch and include schema definitions (default: false for performance)

        • OptionalminBlock?: number
        • OptionalwaitForSync?: number

      Returns Promise<Schema[]>

      Promise resolving to an array of schemas

      // Get all schemas (without definitions for performance)
      const schemas = await vana.schemas.list();

      // Get schemas with definitions
      const schemas = await vana.schemas.list({ includeDefinitions: true });

      // Get schemas with pagination
      const schemas = await vana.schemas.list({ limit: 10, offset: 0 });

    • Retrieves schema definition content directly from a URL.

      Parameters

      • url: string

        The definition URL (typically from schema.definitionUrl)

      Returns Promise<string>

      Promise resolving to the formatted definition content

      Use this method to fetch and format schema definitions from IPFS or HTTP URLs. Automatically uses the SDK's configured download proxy to bypass CORS restrictions. Returns formatted JSON string if content is valid JSON, otherwise raw content.

      When the content cannot be fetched or network errors occur

      const schema = await vana.schemas.get(1);
      const definition = await vana.schemas.retrieveDefinition(schema.definitionUrl);
      console.log(definition); // Pretty-printed JSON

    • Retrieves refinement instruction content from a URL.

      Parameters

      • url: string

        The instruction URL (typically from refiner.refinementInstructionUrl)

      Returns Promise<string>

      Promise resolving to the formatted instruction content

      Use this method to fetch refinement instructions from IPFS or HTTP URLs. Temporarily housed in SchemaController since refiners use schemas and we don't have a dedicated RefinerController yet. Uses the SDK's configured download proxy.

      When the content cannot be fetched or network errors occur

      const instructions = await vana.schemas.retrieveRefinementInstructions(
        refiner.refinementInstructionUrl
      );
      console.log(instructions);

    • Adds a schema using the legacy method (low-level API).

      Parameters

      • params: AddSchemaParams

        Schema parameters including pre-generated definition URL

      Returns Promise<SchemaAddedResult>

      Promise resolving to the add schema result

      Use create() instead for the high-level API with automatic IPFS upload

    Settings

    Member Visibility

    On This Page

    Methods