What is a Registry?
A Registry is the schema template that defines how Primary VDTs are structured, validated, and managed within your organization. Before you create any Primary VDT through the SDK, you must select a Registry — it determines which attributes are required, which can be searched, whether instances are transferable or burnable, and whether on-chain minting applies.
Registries are configured in the ChainIT admin panel and exposed to integrators through the List Registries and Get Registry APIs.
Registry as a Schema Contract
Think of a Registry as a contract between your organization and the ChainIT platform:
- Attributes — the fields each Primary VDT must or may contain (name, slug, data type, section, required/searchable flags)
- Schema version — the active version of that attribute set; VDTs are created against the current version
- Lifecycle rules — whether VDTs minted from this registry can be transferred or burned
- VDT type — Primary VDT registries produce organization-scoped ledger records (distinct from Data VDT registries)
When you call Create Primary VDT, you pass a registryId and an attributesData object keyed by attribute slugs. ChainIT validates every value against the registry schema before persisting the ledger.
Registry Response Fields
| Field | Description |
|---|---|
id | Unique registry identifier — required for all VDT create, list, and search calls |
slug | Human-readable unique slug (e.g. employee-credential) |
name | Display name configured in admin |
type | VDT type produced by this registry (Primary) |
status | Registry availability (ACTIVE, etc.) |
transferable | Whether VDTs from this registry support org-to-org transfer (ERC-721 only) |
burnable | Whether minted VDTs can be permanently burned (ERC-721 custom registries only) |
isDataVdt | Registry implementation type — see Registry types below |
version | Current schema version with full attribute definitions |
Registry Types: ERC-721 vs DataVDT
Every Primary VDT registry is one of two implementation types, determined by isDataVdt on Get Registry:
ERC-721 (isDataVdt: false) | DataVDT (isDataVdt: true) | |
|---|---|---|
| On-chain token | ERC-721 NFT per ledger | Batch-minted Data VDT evidence token |
| Create | options.mint: true required | options.mint optional — false saves a draft, true mints |
| Update | Allowed with options.mint: true (re-mints) | Allowed only while draft (not yet minted) |
| After mint | Can update and re-mint; burn/transfer when registry allows | Immutable — no update, no re-mint |
| Transfer | When transferable: true on registry and instance | Not supported |
| Burn | When burnable: true on custom ERC-721 registry | Not supported |
Check isDataVdt after Get Registry before wiring create, update, transfer, or burn in your UI — the available lifecycle actions depend entirely on this flag.
Registry Attributes
Each attribute in a schema version defines how data is collected, validated, and queried:
| Attribute property | Purpose |
|---|---|
slug | Key used in attributesData when creating or updating a VDT |
name | Display label |
dataType / fieldType | Validation and input type (string, email, dropdown, etc.) |
section | 4W grouping (Who, What, When, Where) for ledger context |
isRequired | Must be supplied on create |
isSearchable | Can be used as a filter in the Search VDTs API |
isPublic / isShareable | Visibility and sharing rules for ledger reads |
Only attributes marked isSearchable: true can be used in the Search Primary VDTs (filter) API.
Working with Registries in an Integration
Step 1 — Discover available registries
Call List Registries to retrieve paginated registries scoped to your organization. Use filters to narrow by name or status if needed.
Step 2 — Inspect schema details
Call Get Registry with the registry id to load the full schema version, attribute list, and lifecycle flags (transferable, burnable). Review required slugs before building your create payload.
Step 3 — Use registryId in VDT APIs
Pass the registryId from the registry response into:
- Create Primary VDT — required in the request body
- Update Primary VDT — required in the request body
- List Primary VDTs — required as a path parameter (
/vdt/list/{registryId}) - Search Primary VDTs — requires the schema version ID (
vdtSchemaId) from the registry version
Registry vs. Primary VDT Instance
| Concept | Registry | Primary VDT |
|---|---|---|
| Role | Schema template | A single tokenized record |
| Created by | Admin panel | SDK API (POST /vdt) |
| Count | Few per use case | Many instances per registry |
| Mutability | Versioned schema updates | Update API changes attribute values |
| Identifier | registryId (UUID) | entityId (business entity ID) |
A Registry defines what can be recorded. A Primary VDT is one recorded instance of that schema.
When to Create a New Registry
Create a separate Registry when:
- A new business object type needs its own attribute schema (e.g. employee vs. equipment)
- Lifecycle rules differ (one credential type is transferable, another is not)
- Compliance requires isolated audit domains with distinct attribute sets
Reuse an existing Registry when the same schema applies to multiple records of the same type.