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.

New to Data Modeling?

If you’re new to data modeling in Vendia, start with the Data Modeling Overview to understand the concepts before diving into the technical details here.

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. See Fine-Grained Data Permissions for details.

"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. Learn more about Indexes.

"x-vendia-indexes": {
  "byStatus": {
    "keys": ["status"]
  },
  "byCustomerAndDate": {
    "keys": ["customerId", "createdAt"]
  }
}

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

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

Performance

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

Security

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

Maintenance

1. Version your schemas using $id
2. Document breaking changes
3. Test schema evolution before deployment

Related Topics

• Data Modeling Guide - Concepts and best practices
• Schema Evolution - How to update schemas safely
• Unique Identifiers - Using unique constraints
• Fine-Grained Data Permissions - Access control setup

JSON Schema Resources

• JSON Schema Official Documentation
• Understanding JSON Schema
• JSON Schema Draft 7 Specification