KSML Vocabulary

KSML is the model source of truth for generated TeaQL APIs. This page is a quick lookup for common modeling terms. When a generated command reports a validation error, use the authoritative modeling rules and the Markdown error report for the final fix.

Core Terms

Term	Meaning
Entity	A business object that becomes part of the generated domain API.
Attribute	A scalar value on an entity, such as name, status, amount, or timestamp.
Relationship	A typed connection between entities.
Root	An aggregate or entry point that defines ownership and traversal boundaries.
Tenant	A boundary used for data isolation and runtime policy.
State	A lifecycle value that should be modeled explicitly when business behavior depends on it.

Attribute Rules

Attributes should be concrete and intentional:

• Do not leave empty attributes.
• Use stable business names.
• Prefer explicit types over ambiguous strings.
• Model sensitive fields with reviewable intent.

Relationship Rules

Relationships should make business traversal clear:

• Use a direct relationship when the model owns the connection.
• Avoid deep nested references when a scalar field is enough.
• Keep tenant and ownership boundaries visible.
• Do not rely on the agent to infer cardinality from examples.

Common Validation Errors

Error	Meaning	Fix
Empty attribute	A tag or attribute has no concrete value.	Delete it or fill it with a valid value.
Depth exceeded	The model has too many nested references.	Remove one nested reference or use a scalar field.
Unknown type	The type name is not recognized by the generator.	Use a supported scalar or entity reference.
Missing root	The model lacks a clear entry point.	Define the aggregate or root boundary.

Agent Guidance

When an AI coding agent edits KSML:

• Read the modeling rules before editing.
• Keep changes small and reviewable.
• Regenerate immediately after model changes.
• Read Markdown diagnostics before applying fixes.
• Do not repair generated code by hand.