Schema Studio

Schema Studio allows you to customize category-specific field mappings. This lets you extend the predefined common data model with custom fields while maintaining unified API consistency across all integrations.

Key Benefit: Extend your data models with custom fields that integrate seamlessly without breaking API compatibility.

Creating and Managing Fields

Open Schema Studio from the left navigation menu.

Access Schema Studio from the Console navigation

1. Select the category you want to extend.
2. Click Configure to view the data model for that category.

Configure category-specific fields

Defining a Custom Unified Field

When creating a new field, provide:

• Key – The actual property key returned in the response
• Label, Type, and Description – Documentation metadata (not included in API responses)

Adding a custom unified field

Mapping to Connector Fields

After defining a custom unified field, map it to source fields from your connected systems.

info

Only connectors enabled on the Connectors page can be mapped.

• Select the source connector field to map
• Use Apply All Suggestions to auto-populate matching fields
• Save your configuration

Mapping custom fields to connector fields

Using Custom Unified Fields

Once mapping is complete, custom fields are automatically included in Unified API responses—no extra configuration needed.

Example Response

{
  "data": [
    {
      "id": "10700",
      "key": "IT-68",
      "name": "test123 update",
      "status": "To Do",
      "priority": "High",
      "type": "Task",
      "targetUrl": "https://example.atlassian.net/rest/api/2/issue/10700",
      "customUnifiedFields": {
        "externalKey": {
          "key": "IT-68"
        }
      },
      "native_response": {
        // Raw source system response
      }
    }
  ]
}

Response Components

Field Category	Location	Description
Normalized Fields	Root level	Common data model attributes
Custom Fields	customUnifiedFields	User-defined field mappings
Source Data	native_response	Original connector response

Note: The customUnifiedFields object contains all configured custom fields with their mapped values from source connectors.

Best Practices

Field Naming Conventions

• Use descriptive, consistent naming patterns
• Avoid special characters and spaces
• Consider future scalability in naming

Data Type Selection

• Choose appropriate data types for source compatibility
• Consider data validation requirements

Mapping Strategy

• Document all field mappings for maintenance
• Test mappings with sample data before production
• Establish validation procedures for data accuracy

Troubleshooting

Common Issues

Field Not Appearing in API Response

• Verify mapping configuration is complete
• Check connector compatibility
• Ensure field definition is saved properly

Data Type Mismatch

• Review source connector data types
• Adjust custom field type definition
• Test with sample data

---

For additional support, contact our team at support@unizo.ai.