Skip to main content

Define a Collection

To store data in SecretVault, you'll need to define a Collection with a JSON Schema, which creates a structured container for your records (individual pieces of data). This has two main effects:

  1. Creates a Collection in SecretVault for your data
  2. Links the Collection to your Organization and validates all records before storage, ensuring they adhere to the JSON Schema

You can create schema collections programatically or using the SecretVault Tools UI:

Upload a Schema using the SecretVault Tools UI​

Nillion SecretVault Tools is a web application to help developers manage Nillion SecretVault schemas and collections. This tool allows you to create, validate, and upload JSON schemas to your SecretVault organization, as well as view and manage your schema collections and their records.

Schema Tools UI

Key Features​

  • Set your organization configuration: Easily configure and manage your SecretVault organization settings directly from the UI.

  • Create and upload custom schemas: Design and validate new JSON schemas tailored to your data needs, then upload them directly to nodes

  • View schema collections and records: Browse your existing schema collections and view individual records

  • Show example records: View sample records to better understand your data structure and schema usage

Upload a Schema Programatically​

1. Plan Your Collection's Data Structure​

Sketch out your data structure to plan the fields and types that will define your collection's JSON schema. Here's an example:

Example Data
years_in_web3 = 3 //integer, encrypted
responses = [] //array
  question_number = 1 //integer
  rating = 5 //integer

2. Create the JSON Schema​

Convert your data structure into a JSON Schema following these requirements:

  • Use JSON Schema draft-07, type "array"
  • Each record needs a unique _id (UUID format, coerce: true)
  • Use "date-time" format for dates (coerce: true)
  • Remember to take into account the type for fields that you want to encrypt using %allot/%share
  • Mark required fields (_id is always required)
  • Set additionalProperties to false
  • Avoid "$" prefix in field names to prevent query conflicts
  • Note: System adds _created and _updated fields automatically

Use a JSON Schema validator tool to make sure your collection's schema is valid.

Example JSON Schema
examples/store/schema.json
loading...

3. Use the Create Schema API to Create your Schema and Collection​

Decide on a collection name and generate a UUID4 for the Collection ID (use identical UUID across all Cluster nodes).

Select which fields should act as primary keys / unique identifiers (_id should always be included).

Then use the Create Schema endpoint to upload your JSON schema to each node in your organization using valid API tokens for each node.

Example POST /schemas Payload
{
  "_id": "9b22147f-d6d5-40f1-927d-96c08XXXXXXXX",
  "name": "Web3 Experience Survey",
  "keys": ["_id"],
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Web3 Experience Survey",
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "_id": {
          "type": "string",
          "format": "uuid",
          "coerce": true
        },
        "years_in_web3": {
          "type": "object",
          "properties": {
            "%share": {
              "type": "string"
            }
          },
          "required": ["%share"]
        },
        "responses": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "rating": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              },
              "question_number": {
                "type": "integer",
                "minimum": 1
              }
            },
            "required": ["rating", "question_number"]
          },
          "minItems": 1
        }
      },
      "required": ["_id", "years_in_web3", "responses"]
    }
  }
}
Code Samples
nildb/secretvault_python/define_collection.py
loading...
nildb/secretvault_python/nildb_api.py
loading...

Schema collections are immutable. If you need to make changes to your schema, use the DELETE /schema API endpoint to delete your current schema, then redo this step to re-create your updated schema.