This playbook is for architects creating robust OT/DT templates for teams and integrations.
Before creating a template, decide:
- Is this template advisory or strict?
- Which fields are mandatory for interoperability?
- Which fields 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, internal standard).
- Define minimal required output schema.
- Create initial version with clear naming.
- Document migration intent for future replacement versions.
- Keep semantic versioning style in version descriptions.
¶ Step 3: Add required columns first
For each required column:
- Choose column type.
- Add one or more specs.
- For each spec define data type, size, validation, flags, and settings.
- Decide whether this column is truly required.
Best practice:
- Keep one “safe default” spec and optional stricter specs.
Use fixed settings when downstream systems rely on strict schema.
Good candidates for fixed values:
- primary time data type
- identifier strategy
- validation ranges and regex for critical fields
- required table-level flags and settings
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 ecosystem variation is expected.
Choose one:
- strict mode: no additional columns
- controlled mode: additional columns allowed with key fixed constraints
Strict mode is better for hard integration contracts.
Controlled mode is better for internal innovation.
- Set version to Active when validated.
- Test with wizard-created OT/DT in a staging project.
- Verify generated PostgreSQL constraints and API behavior.
When changing structure:
- Create a new template version.
- Keep old version active or deprecate based on rollout plan.
- If deprecating, set target replacement version.
- Communicate migration window and compatibility notes.
- Migrate projects in waves.
Avoid editing 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.
- Required columns are complete.
- Primary time and identifier logic is unambiguous.
- Validation rules match expected payload ranges.
- Parent/reference restrictions are intentional.
- Additional-columns policy matches governance needs.
- Migration path is defined for future versions.