# 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 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 ## JSON Schema Resources - [JSON Schema Official Documentation](https://json-schema.org/) - [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) - [JSON Schema Draft 7 Specification](https://json-schema.org/draft-07/schema)