Deep Dive: Schemas
This page is under construction! I'm working on it :)
Schemas
A schema defines the shape of data your device sends. It tells Inventronix Connect what fields to expect, what types they should be, and how to validate them.
Why Schemas?
Without schemas, any random JSON could be sent to your project. Schemas give you:
- Validation - Reject malformed data before it pollutes your database
- Type safety - Ensure temperature is always a number, not a string
- Documentation - See at a glance what data your project expects
- Multiple formats - Support different device types sending different data shapes
Creating a Schema
From your project page, click Schemas → New Schema.
[IMAGE: New schema button]
Give your schema a name and optional description, then add fields.
[IMAGE: Schema editor with fields]
Field Types
Every field has a type that determines what values are valid and what validators are available.
String
Text values. Use for status messages, device names, or any non-numeric data.
1 | |
Number
Numeric values (integers or decimals). Use for sensor readings, counts, percentages.
1 | |
Boolean
True or false values. Use for on/off states, flags, binary sensors.
1 | |
Validators
Validators add rules to your fields. A payload is rejected if any validator fails.
All Types
- isRequired - Field must be present in the payload
String Validators
- isNotEmpty - String cannot be empty ("")
- isEqualTo - Must match exact value
- isNotEqualTo - Must not match value
Number Validators
- isEqualTo - Must equal value
- isNotEqualTo - Must not equal value
- isGreaterThan - Must be > value
- isLessThan - Must be < value
- isGreaterThanOrEqualTo - Must be >= value
- isLessThanOrEqualTo - Must be <= value
Boolean Validators
- isEqualTo - Must be true or false
- isNotEqualTo - Must not be value
Required vs Optional Fields
By default, fields are optional. If your payload doesn't include an optional field, it's simply ignored.
Add the `isRequired` validator to make a field mandatory:
[IMAGE: Adding isRequired validator to a field]
Example:
Schema with:
- `temperature` (number, required)
- `humidity` (number, optional)
- `location` (string, optional)
Valid payloads:
1 | |
Invalid payload (missing required field):
1 | |
Lifecycle States
Schemas have three lifecycle states:
Draft
- Schema is being designed
- Cannot receive data - payloads won't match draft schemas
- Safe to edit freely
Active
- Schema is live and receiving data
- Payloads will be validated against this schema
- Be careful editing - changing field types or adding required fields may break existing devices
Deprecated
- Schema is retired but still visible
- Cannot receive new data - payloads won't match deprecated schemas
- Historical data is preserved
- Use this instead of deleting to keep your data intact
[IMAGE: Lifecycle dropdown in schema editor]
Multiple Schemas
A project can have multiple active schemas. This is useful when:
- Different device types send different data (e.g., temperature sensor vs motion sensor)
- Schema evolution - you want to support old and new payload formats during migration
When a payload arrives, Inventronix tries to match it against all active schemas. The first match wins.
If your payload could match multiple schemas, use the `X-Schema-ID` header to specify which one to use.
Viewing Invalid Payloads
When a payload fails validation, it's logged for debugging. Check the Health panel in your project toolbar to see recent validation failures.
[IMAGE: Health check showing validation failures]
You can also use the Live Debug panel to watch validation in real-time.
Schema Design Tips
Start Simple
Begin with just the fields you need. You can always add optional fields later without breaking existing devices.
Use Descriptive Names
Field names appear in dashboards and rules. `temperature_celsius` is clearer than `temp` or `t`.
Validate at the Edges
Use validators to catch bad data early. It's easier to reject `temperature: -999` at ingestion than to filter it out everywhere else.
Plan for Evolution
When you need to change a schema significantly:
- Create a new schema with the new structure
- Update your devices to use the new schema
- Deprecate the old schema once all devices are migrated
Example: Weather Station Schema
A complete schema for a weather monitoring device:
- temperature (number) - isRequired, isGreaterThanOrEqualTo: -50, isLessThanOrEqualTo: 60 - Temperature in °C
- humidity (number) - isRequired, isGreaterThanOrEqualTo: 0, isLessThanOrEqualTo: 100 - Relative humidity %
- pressure (number) - isGreaterThanOrEqualTo: 800, isLessThanOrEqualTo: 1200 - Barometric pressure hPa
- battery (number) - isGreaterThanOrEqualTo: 0, isLessThanOrEqualTo: 100 - Battery level %
- location (string) - Optional location identifier
[IMAGE: Complete weather station schema in editor]
Next Steps
- Sending Data - How to send payloads to your schemas
- Rules and Actions - Trigger actions based on your data
- Debugging - Troubleshoot validation failures