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

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/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.