Vendia Schema Reference | Vendia

Vendia Schema Reference

The vendia-schema.json file is the foundation of your Vendia project. It defines the data model, entities, fields, and configuration that Vendia uses to generate your distributed application. This reference guide explains the complete structure and all available options.

Basic Schema Structure

Every vendia-schema.json file follows this basic structure:

{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://vendia.com/schemas/your-schema.json",

"title": "Your Project Schema",

"description": "Description of your data model",

"type": "object",

"x-vendia-acls": {

// Fine-grained access control definitions (optional)

},

"properties": {

// Your entity definitions go here

}

}

Required Fields

`$schema`

Type: String
Required: Yes
Value: "http://json-schema.org/draft-07/schema#"
Description: Specifies the JSON Schema version. Vendia supports draft-07.

"$schema": "http://json-schema.org/draft-07/schema#"

`type`

Type: String
Required: Yes
Value: "object"
Description: The root type must always be “object” for Vendia schemas.

"type": "object"

`properties`

Type: Object
Required: Yes
Description: Contains all entity definitions. Each top-level property becomes a Vendia Entity.

"properties": {

"Product": { /* entity definition */ },

"Order": { /* entity definition */ },

"Customer": { /* entity definition */ }

}

Optional Top-Level Fields

`$id`

Type: String
Required: No (but recommended)
Description: Unique identifier for your schema. Useful for documentation and tooling.

"$id": "http://vendia.com/schemas/ecommerce.json"

`title`

Type: String
Required: No (but recommended)
Description: Human-readable name for your schema.

"title": "E-commerce Data Model"

`description`

Type: String
Required: No (but recommended)
Description: Explanation of what your schema represents.

"description": "Data model for our e-commerce platform including products, orders, and customers"

`x-vendia-acls`

Type: Object
Required: No
Description: Defines fine-grained access control lists.

"x-vendia-acls": {

"Product": {

"type": "Product"

},

"Order": {

"type": "Order"

}

}

Entity Definitions

Each property in the properties object defines an entity. Entities are the core data structures in your project.

Basic Entity Structure

"EntityName": {

"description": "Description of this entity",

"type": "array",

"items": {

"type": "object",

"properties": {

// Field definitions go here

},

"required": ["field1", "field2"],

"additionalProperties": false

}

}

Entity Properties

Entity `description`

Type: String
Required: No (but recommended)
Description: Explains what this entity represents.

Entity `type`

Type: String
Required: Yes
Value: "array"
Description: Defines the entity as a collection of items.

`items`

Type: Object
Required: Yes
Description: Defines the structure of each item in the array.

`properties` (within items)

Type: Object
Required: Yes
Description: Defines the fields within the entity.

`required`

Type: Array of strings
Required: No
Description: Lists which fields are mandatory.

`additionalProperties`

Type: Boolean
Required: No
Default: true
Description: Controls whether additional fields beyond those defined are allowed.

Field Types

Scalar Types

String Fields

"fieldName": {

"type": "string",

"description": "Field description",

"minLength": 1,

"maxLength": 100,

"pattern": "^[A-Za-z]+$",

"format": "email"

}

String Constraints:

minLength: Minimum character length
maxLength: Maximum character length
pattern: Regular expression pattern
format: Predefined formats (email, date-time, uri, etc.)

Number Fields

"price": {

"type": "number",

"description": "Product price",

"minimum": 0,

"maximum": 10000

}

Number Constraints:

minimum: Minimum value
maximum: Maximum value

Integer Fields

"quantity": {

"type": "integer",

"description": "Item quantity",

"minimum": 0,

"maximum": 1000

}

Boolean Fields

"isActive": {

"type": "boolean",

"description": "Whether the item is active"

}

Date and Time Fields

"createdAt": {

"type": "string",

"format": "date-time",

"description": "When the record was created"

},

"birthDate": {

"type": "string",

"format": "date",

"description": "Date of birth"

},

"eventTime": {

"type": "string",

"format": "time",

"description": "Time of the event"

}

Complex Types

Object Fields

"address": {

"type": "object",

"description": "Customer address",

"properties": {

"street": { "type": "string" },

"city": { "type": "string" },

"zipCode": { "type": "string" }

},

"required": ["street", "city"]

}

Array Fields

"tags": {

"type": "array",

"description": "Product tags",

"items": {

"type": "string"

},

"minItems": 1,

"maxItems": 10,

"uniqueItems": true

}

Array Constraints:

minItems: Minimum number of items
maxItems: Maximum number of items
uniqueItems: Whether items must be unique

Enum Fields

"status": {

"type": "string",

"enum": ["pending", "approved", "rejected"],

"description": "Order status"

}

Vendia-Specific Extensions

Unique Identifiers

Mark fields as unique using x-vendia-unique. Learn more about unique identifiers.

"email": {

"type": "string",

"format": "email",

"x-vendia-unique": true,

"description": "Unique email address"

}

Indexes

Create indexes for efficient querying.

"x-vendia-indexes": {

"OrderStatusIndex": [

{

"type": "Order",

"property": "status"

}

],

"OrderCustomerDateIndex": [

{

"type": "Order",

"property": "customerId"

}

]

}

Complete Example

Here’s a comprehensive example showing all major features:

{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://vendia.com/schemas/ecommerce.json",

"title": "E-commerce Platform Schema",

"description": "Complete data model for an e-commerce platform",

"type": "object",

"x-vendia-acls": {

"Product": { "type": "Product" },

"Order": { "type": "Order" },

"Customer": { "type": "Customer" }

},

"properties": {

"Product": {

"description": "Product catalog",

"type": "array",

"items": {

"type": "object",

"properties": {

"id": {

"type": "string",

"x-vendia-unique": true,

"description": "Unique product identifier"

},

"name": {

"type": "string",

"minLength": 1,

"maxLength": 200,

"description": "Product name"

},

"price": {

"type": "number",

"minimum": 0,

"description": "Product price in USD"

},

"category": {

"type": "string",

"enum": ["electronics", "clothing", "books", "home"],

"description": "Product category"

},

"inStock": {

"type": "boolean",

"description": "Whether product is in stock"

},

"tags": {

"type": "array",

"items": { "type": "string" },

"uniqueItems": true,

"description": "Product tags"

},

"createdAt": {

"type": "string",

"format": "date-time",

"description": "Product creation timestamp"

}

},

"required": ["id", "name", "price", "category"],

"additionalProperties": false

}

},

"Customer": {

"description": "Customer information",

"type": "array",

"items": {

"type": "object",

"properties": {

"id": {

"type": "string",

"x-vendia-unique": true,

"description": "Unique customer identifier"

},

"email": {

"type": "string",

"format": "email",

"x-vendia-unique": true,

"description": "Customer email address"

},

"name": {

"type": "string",

"minLength": 1,

"description": "Customer full name"

},

"address": {

"type": "object",

"properties": {

"street": { "type": "string" },

"city": { "type": "string" },

"state": { "type": "string" },

"zipCode": { "type": "string" }

},

"required": ["street", "city", "state", "zipCode"]

}

},

"required": ["id", "email", "name"],

"additionalProperties": false

}

},

"Order": {

"description": "Customer orders",

"type": "array",

"items": {

"type": "object",

"properties": {

"id": {

"type": "string",

"x-vendia-unique": true,

"description": "Unique order identifier"

},

"customerId": {

"type": "string",

"description": "Reference to customer"

},

"items": {

"type": "array",

"items": {

"type": "object",

"properties": {

"productId": { "type": "string" },

"quantity": { "type": "integer", "minimum": 1 },

"price": { "type": "number", "minimum": 0 }

},

"required": ["productId", "quantity", "price"]

},

"minItems": 1

},

"total": {

"type": "number",

"minimum": 0,

"description": "Order total amount"

},

"status": {

"type": "string",

"enum": [

"pending",

"processing",

"shipped",

"delivered",

"cancelled"

],

"description": "Order status"

},

"createdAt": {

"type": "string",

"format": "date-time",

"description": "Order creation timestamp"

}

},

"required": ["id", "customerId", "items", "total", "status"],

"additionalProperties": false

}

}

}

}

Best Practices

Schema Design

Use descriptive names for entities and fields
Add descriptions to all entities and important fields
Define required fields appropriately
Set appropriate constraints (min/max values, string lengths)
Use enums for fields with predefined values

Performance

Mark unique fields with x-vendia-unique
Create indexes for frequently queried fields
Limit nested array depth for better performance
Consider entity relationships carefully

Security

Use fine-grained ACLs when needed
Validate data formats with constraints
Set additionalProperties to false for strict schemas

Maintenance

Version your schemas using $id
Document breaking changes
Test schema evolution before deployment