Custom Structures

Custom structures in Kinesis API provide a way to create reusable, complex data templates that can be referenced across multiple collections. They function as user-defined object types that encapsulate related fields, enabling more sophisticated data modeling than is possible with basic structures alone.

Understanding Custom Structures

While regular structures define individual fields within a collection, custom structures allow you to define composite data types with multiple fields grouped together. Think of them as objects or complex data types that:

• Act as templates for complex data
• Can be reused across multiple collections
• Encapsulate related fields
• Support nested data models
• Enable modular data design

Accessing Custom Structures

Custom structures are managed through the collection interface but have their own dedicated pages:

1. Navigate to a project page
2. Select a collection
3. Find the "Custom Structures" section
4. Click on a custom structure name to access its dedicated page

Creating a Custom Structure

To create a new custom structure:

1. From a collection page, find the "Custom Structures" section
2. Click the "Create New" button
3. Fill in the required information:
   • Name: A descriptive name for the custom structure
   • ID: A unique identifier used in API references
   • Description: An explanation of the custom structure's purpose
4. Click "Create" to save the custom structure

Custom Structure Detail Page

After creating a custom structure, you can access its detail page by clicking on its name. The custom structure page allows you to:

• View and edit the custom structure's information
• Add structures (fields) to the custom structure
• Manage existing structures
• Delete the custom structure

Managing Custom Structure Information

From the custom structure page, you can modify various aspects:

Updating Custom Structure ID

1. Click the "Update Custom Structure ID" button
2. Enter the new ID in the modal
3. Click "Submit" to save the changes

Updating Custom Structure Name

1. Click the "Update Custom Structure Name" button
2. Enter the new name in the modal
3. Click "Submit" to save the changes

Updating Custom Structure Description

1. Click the "Update Custom Structure Description" button
2. Enter the new description in the modal
3. Click "Submit" to save the changes

Adding Structures to a Custom Structure

To add a field to a custom structure:

1. From the custom structure page, click the "Create New" button in the Structures section
2. Fill in the field details:
   • Name: Field name
   • ID: Field identifier
   • Description: Field description
   • Type: Data type selection
   • Additional properties like min/max values, default value, etc.
3. Click "Create" to add the field

The process for adding fields to a custom structure is identical to adding structures to a collection. See the Structures documentation for more details on field types and properties.

Example Use Cases

Custom structures are particularly useful for:

Address Information

Create an "Address" custom structure with fields like:

• Street
• City
• State/Province
• Postal Code
• Country

This can then be used in "Customer", "Shipping", "Billing" and other collections.

Contact Details

Build a "Contact Info" custom structure containing:

• Email
• Phone
• Website
• Social Media Profiles

Product Specifications

Define "Product Specs" with varying attributes based on product type:

• Dimensions
• Weight
• Material
• Technical Specifications

Modifying Custom Structures

When you modify a custom structure by adding, changing, or removing fields, these changes affect all places where the custom structure is used. This provides a powerful way to update data models across your entire API without making changes in multiple locations.

However, be aware that:

• Removing fields from a custom structure could impact existing data
• Changing field types might require data migration
• Adding required fields to an existing custom structure could cause validation errors

Deleting Custom Structures

To delete a custom structure:

1. From the custom structure page, click the "Delete Custom Structure" button
2. Confirm the deletion in the modal that appears

⚠️ Warning: Deleting a custom structure will affect all places where it's used. Ensure it's not referenced by any other structures before deletion.

Best Practices

When working with custom structures:

1. Descriptive Naming: Use clear, descriptive names that indicate the custom structure's purpose
2. Logical Grouping: Group related fields that naturally belong together
3. Appropriate Granularity: Create custom structures at the right level of detail
4. Reusability: Design custom structures to be reusable across multiple collections
5. Documentation: Add thorough descriptions to help team members understand the purpose and usage of each custom structure
6. Versioning Strategy: Consider how to handle changes to custom structures over time

Related Documentation

• Collections - Managing collections that contain custom structures
• Structures - Understanding basic structures and field types
• Data - Working with data based on complex structures