Understanding Supported Schemas

Zluri SDK uses predefined schemas to structure the data you push into the platform. These schemas ensure consistency, validation, and proper mapping of information across users, apps, licenses, and more.

Before uploading data, it's important to understand the supported entities and the difference between Snapshot and Incremental data models.

Supported Entity:

Entity Type	Description
`users`	Employee or user profile details
`user_activity`	Login or activity events from apps
`groups`	Organizational or functional groupings
`group_users`	Mapping of users to their groups
`transactions`	SaaS payments and subscription spend
`contracts`	Vendor contract metadata

Data Models

Snapshot Data: Represents the current state of an entity (e.g., a user's current role or license). It replaces any previous data for that entity type during the sync.
- Users
- Groups
- Group-users
Incremental Data: Represents time-based, historical data (e.g., user login activity or payment transactions). It appends to the existing records and never overwrites.
- Contracts
- Transactions
- User-activity

Key Differences between Snapshot and Incremental Data

Aspect	Snapshot Data	Incremental Data
Nature	Current state	Historical events
Time	Point-in-time	Time-series
Updates	Replaces previous state	Adds to history
Example	"John is currently active"	"John logged in at 2PM"
Use Case	Employee management	Activity tracking
Processing	Latest sync wins	All events preserved

Cross-Entity Relationship

Entity	Depends On	Validation Requirement
`users`	–	Can be uploaded independently
`groups`	–	Can be uploaded independently
`contracts`	–	Can be uploaded independently
`transactions`	–	Can be uploaded independently
`user_activity`	`users`	Each activity record must reference a valid user — user entity must be present in the sync
`group_users`	`groups`&`users`	Must reference a valid user and group — both entities must be present in the sync

Data Schema

The following dropdowns show example schemas for each supported entity.

Entity:`users`

users schema

{
"entity_name": "users",
"version": "v2",
"schema": {
  "type": "array",
  "required": [
    "work_email",
    "unique_id"
  ],
  "items": {
    "type": "object",
    "properties": {
      "work_email": {
        "type": "string",
        "format": "email",
        "maxLength": 255,
        "description": "Primary email address"
      },
      "personal_email": {
        "type": [
          "string",
          "null"
        ],
        "format": "email",
        "maxLength": 255,
        "description": "Personal email address"
      },
      "name": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Full name"
      },
      "user_name": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "User login name"
      },
      "first_name": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "First name"
      },
      "last_name": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Last name"
      },
      "reporting_manager_email": {
        "type": [
          "string",
          "null"
        ],
        "format": "email",
        "maxLength": 255,
        "description": "Manager's email"
      },
      "department": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Department name"
      },
      "job_title": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Job title/position"
      },
      "created_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Account creation date"
      },
      "cost_center": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Cost center name"
      },
      "cost_center_code": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Cost center identifier"
      },
      "business_unit": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Business unit"
      },
      "location": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Work location"
      },
      "date_of_joining": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Start date"
      },
      "date_of_termination": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "End date"
      },
      "employee_type": {
        "type": "string",
        "maxLength": 255,
        "description": "Employee classification"
      },
      "alternate_emails": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string",
          "format": "email",
          "maxLength": 255
        },
        "description": "Additional email addresses"
      },
      "unique_id": {
        "type": "string",
        "maxLength": 255,
        "minLength": 1,
        "description": "Unique identifier"
      },
      "modified_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Last modified date"
      },
      "profile_picture": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 255,
        "description": "Profile image"
      },
      "custom_fields": {
        "type": [
          "object",
          "null"
        ],
        "maxProperties": 100,
        "additionalProperties": {
          "type": [
            "string",
            "number",
            "boolean",
            "null"
          ],
          "maxLength": 255
        },
        "propertyNames": {
          "maxLength": 255
        }
      },
      "status": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "active",
          "inactive",
          "suspended"
        ],
        "description": "Account status"
      },
      "last_login": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Last login time"
      },
      "roles": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "license_names": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        },
        "description": "List of assigned licenses for the user"
       }
     }
   }
 }
}

Entity:`user_activity`

user_activity schema

{
  "entity_name": "user_activity",
  "version": "v2",
  "schema": {
  		 "required": [
        "activity_id",
        "application_name",
        "timestamp",
        "work_email"
      ],
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "activity_id": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Unique activity identifier"
        },
        "log_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Type of log entry"
        },
        "app_id": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Application identifier"
        },
        "app_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "maxLength": 255,
          "description": "Application URL"
        },
        "application_name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Name of the application"
        },
        "location_city": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "City location"
        },
        "location_state": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "State or province location"
        },
        "location_country": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Country location"
        },
        "geo_location_codes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Geolocation codes"
        },
        "ip": {
          "type": [
            "string",
            "null"
          ],
          "format": "ipv4",
          "maxLength": 45,
          "description": "IP address"
        },
        "device": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500,
          "description": "Device and browser information"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "minLength": 1,
          "description": "Activity timestamp"
        },
        "event_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Type of event"
        },
        "user_id": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "User identifier",
          "refersTo": {
            "entity": "users",
            "key": "unique_id"
          }
        },
        "work_email": {
          "type": "string",
          "format": "email",
          "maxLength": 255,
          "minLength": 1,
          "description": "User work email address"
        }
      }
    }
  }
}

Entity:`groups`

group schema

{
  "entity_name": "groups",
  "version": "v2",
  "schema": {
     "required": [
        "group_id",
        "group_name"
      ],
  		"type": "array",
    "items": {
      "type": "object",
      "properties": {
        "group_id": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Unique group identifier"
        },
        "group_name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Name of the group"
        },
        "group_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Type or category of the group"
        }
      }
    }
  }
}

Entity:`groups_users`

group_users schema

{
  "entity_name": "group_users",
  "version": "v2",
  "schema": {
  		"required": [
        "group_id",
        "group_name",
        "group_users"
      ],      
  		"type": "array",
    "items": {
      "type": "object",
      "properties": {
        "group_id": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Unique group identifier",
          "refersTo": {
            "entity": "groups",
            "key": "group_id"
          }
        },
        "group_name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Name of the group"
        },
        "group_users": {
                        "required": [
              "user_id",
              "work_email"
            ],
  					"type": "array",
          "items": {
            "type": "object",
            "properties": {
              "user_id": {
                "type": "string",
                "maxLength": 255,
                "minLength": 1,
                "description": "User identifier",
                "refersTo": {
                  "entity": "users",
                  "key": "unique_id"
                }
              },
              "work_email": {
                "type": "string",
                "format": "email",
                "maxLength": 255,
                "description": "User work email address"
              }
            }
          },
          "description": "List of users in this group"
        }
      }
    }
  }
}

Entity:`transactions`

transactions schema

{
  "entity_name": "transactions",
  "version": "v2",
  "schema": {
    "required": [
        "transaction_id",
        "date",
        "description",
        "amount",
        "currency_code"
      ],
  		"type": "array",
    "items": {
      "type": "object",
      "properties": {
        "transaction_id": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Unique transaction identifier"
        },
        "date": {
          "type": "string",
          "format": "date-time",
          "description": "Transaction date and time"
        },
        "description": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1,
          "description": "Transaction description"
        },
        "amount": {
          "type": "number",
          "minimum": 0,
          "description": "Transaction amount"
        },
        "currency_code": {
          "type": "string",
          "maxLength": 3,
          "minLength": 1,
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code"
        },
        "vendor": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Vendor or supplier name"
        },
        "account_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Type of account"
        },
        "account_name": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Name of the account"
        },
        "transaction_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Type of transaction"
        },
        "tax_amount": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Tax amount"
        },
        "gl_code": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "General ledger code"
        },
        "amortization_start_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Amortization start date"
        },
        "amortization_end_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Amortization end date"
        },
        "paid_by_user_email": {
          "type": [
            "string",
            "null"
          ],
          "format": "email",
          "maxLength": 255,
          "description": "Email of user who made the payment"
        },
        "cost_center_code": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Cost center code"
        },
        "cost_center_name": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Cost center name"
        },
        "department": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Department name"
        },
        "exchange_rate": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Currency exchange rate"
        }
      }
    }
  }
}

Entity:`contracts`

contracts schema

{
  "entity_name": "contracts",
  "version": "v2",
  "schema": {
    "required": [
        "contract_id",
        "app_name",
        "name",
        "start_date",
        "licenses"
      ],
  		"type": "array",
    "items": {
      "type": "object",
      "properties": {
        "contract_id": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Unique contract identifier"
        },
        "name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Contract name or title"
        },
        "app_name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "description": "Application name"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000,
          "description": "Contract description"
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Contract status"
        },
        "start_date": {
          "type": "string",
          "format": "date-time",
          "minLength": 1,
          "description": "Contract start date"
        },
        "end_date": {
          "type": "string",
          "format": "date-time",
          "description": "Contract end date"
        },
        "payment_terms": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Payment terms and conditions"
        },
        "contract_owner": {
          "type": [
            "string",
            "null"
          ],
          "format": "email",
          "maxLength": 255,
          "description": "Contract owner email"
        },
        "term_type": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255,
          "description": "Contract term type"
        },
        "attachments_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "maxLength": 500,
          "description": "URL to contract attachments",
          "refersTo": {
            "entity": "contracts",
            "key": "attachments_url"
          }
        },
        "total_amount": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Total contract amount"
        },
        "currency_code": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 3,
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code"
        },
        "licenses": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "license_id": {
                "type": "string",
                "maxLength": 255,
                "minLength": 1,
                "description": "Associated license identifier"
              },
              "license_name": {
                "type": "string",
                "maxLength": 255,
                "minLength": 1,
                "description": "License name"
              },
              "cost_of_license": {
                "type": "number",
                "minimum": 0,
                "description": "Total cost of the license"
              },
              "licenses_cost_per_month": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0,
                "description": "Monthly cost of licenses"
              },
              "license_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "description": "Number of licenses"
              }
            },
            "required": [
              "license_id",
              "license_name",
              "cost_of_license"
            ]
          },
          "description": "List of licenses in this contract"
        }
      }
    }
  }
}