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:
- Creates a Collection in SecretVault for your data
- Links the Collection to your Organization and validates all records before storage, ensuring they adhere to the JSON Schema
You can create schema collections using the SecretVault Tools UI or programatically:
- Secret Vaults Tools UI
- Programatic
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.
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
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
- Python
- TypeScript
- JavaScript (with wrapper)
- Python (with wrapper)
loading...
loading...
loading...
Install secretvaults
npm i secretvaults
Run the createSchema script
node createSchema.js
- createSchema.js
- orgConfig.js
loading...
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.