A step-by-step guide for architects creating OT/DT templates.
Decide:
- Is this template advisory (recommendations) or strict (locked constraints)?
- Which columns are mandatory for interoperability?
- Which values may be customized per project?
- How will future versions stay backward-compatible?
- Choose: Object structure template or Data table template
- Define intended use (driver, domain standard, internal convention)
- Define the minimal required output schema
- Create initial version with clear naming
- Document migration intent for future versions
- Use semantic versioning style in version descriptions
¶ Step 3: Add required columns
For each required column:
- Choose column type (see Creating Tables for available types)
- Add one or more specs (data type, size, validation, flags)
- Mark column as required or optional
Tip: Keep one "safe default" spec and optional stricter specs.
Good candidates for fixed values:
- Primary time data type
- Identifier strategy
- Validation ranges/regex for critical fields
- Required table-level flags
Leave flexible:
- Display labels
- Optional metadata
- Non-critical extra columns
- Restrict allowed parent versions if hierarchy semantics matter
- Restrict allowed reference versions if cross-structure relations matter
- Allow custom parent/reference only when variation is expected
¶ Step 6: Additional-columns policy
| Mode |
When to use |
| Strict (no additional columns) |
Hard integration contracts |
| Controlled (additional columns allowed) |
Internal innovation, flexible metadata |
- Set version to Active when validated
- Test with wizard-created OT/DT in a staging project
- Verify generated PostgreSQL constraints and API behavior
- Create new template version
- Keep old version Active or Deprecate based on rollout plan
- If deprecating, set target replacement version
- Communicate migration window
- Migrate projects in waves
Never edit old Active versions in ways that break existing generated structures.
- Over-fixing every value (blocks real project usage)
- Under-fixing critical integration fields (breaks interoperability)
- Mixing unrelated domains into one template
- Reusing generic names that hide semantic purpose