Skip to main content

KSML Quick Guide

Applicable to: Domain Modeling / Architecture Design / Schema Review / Automated Code Generation

KSML is a strict subset of XML, used to describe business domain relationship models (Domain Models).

1. What is KSML​

  • KSML is a strict subset of XML and must comply with XML specifications
  • Used to describe:
    • Domain objects
    • Object attributes
    • Relationships between objects
  • Designed for:
    • Semantic stability
    • Clear structure
    • Cross-system consistency
    • Automatic code / schema / DSL generation

2. Root Structure Rules​

  • A system must have exactly one <root>
  • <root> is the parent of all domain objects
  • Except for constant (finite-set) objects, no element may be nested
  • The model is flat under <root>

Correct Example​

<root>
  <school name="NYC University" create_time="createTime()" />
  <department name="CS Department" school="school()" create_time="createTime()" />
</root>

Incorrect Example: Nested Objects​

<root>
  <school name="NYC University" create_time="createTime()">
    <department name="CS Department" school="school()" create_time="createTime()" />
  </school>
</root>

3. Object (Element) Rules​

  • Each object type must be defined by one unique XML element
  • The same element name may appear only once
  • Relationships are expressed via attribute references, not duplication

Incorrect Example: Duplicate Elements​

<root>
  <department name="CS Department" school="school()" create_time="createTime()" />
  <department name="ES Department" school="school()" create_time="createTime()" />
</root>

4. Naming Conventions (Mandatory)​

  • Element names: lowercase
  • Attribute names: lowercase
  • Words separated by underscores
  • Attribute values use natural writing
  • Avoid keywords from:
    • Java
    • SQL2016
    • JavaScript
    • Dart
    • Rust
    • Golang
    • Python

5. Metadata Attributes (Required)​

Every element must declare:

AttributeMeaning
_nameDisplay name
_moduleBusiness module
_module_keyInternal workbench key (English)

6. Attributes and Object References​

Regular Attributes​

  • Attribute values are example values
  • Dates use ISO-8601 format
birth_date="2022-05-20"

Object References​

  • Do not use _id suffix
  • Do not specify ID explicitly
  • Use object_name() syntax
school="school()"
child="child()"

7. ID / Version Rules​

  • Normal objects must not declare id or version
  • Only constant (finite-set) objects may declare id

8. Constant (Finite-Set) Objects​

Used for enums, statuses, and fixed classifications.

Mandatory Rules​

  • Must declare:
    • id="id()"
    • name="string()"
    • code="string()"
  • Must declare:
    • _constant="true"
    • _identifier="code"
  • Enumeration values are defined using <_value>
  • _value.id starts from 1

Example​

<gender_type
  _name="Gender Type"
  _module="basic data"
  _module_key="basic_data"
  id="id()"
  name="string()"
  code="string()"
  merchant="merchant(context)"
  _constant="true"
  _identifier="code"
>
  <_value id="1" name="Male" code="MALE" />
  <_value id="2" name="Female" code="FEMALE" />
</gender_type>

9. Built-in System Attribute Values​

Built-in values are case-sensitive and do not use underscores.

Built-in ValueMeaning
createTime()Creation time
updateTime()Last update time
currentUser()Last operating user
remoteIp()Source IP address
cityByIp()City resolved from IP

Example Usage​

create_time="createTime()"
update_time="updateTime()"

10. Multi-Tenancy: Merchant​

A merchant object must be defined.

<merchant
  _name="Merchant"
  _module="organization"
  _module_key="organizational_structure"
  name="Sunshine Child Development Center"
  external_id="91370100MA3C6B4A2Y"
  platform="platform()"
  create_time="createTime()"
  update_time="updateTime()"
/>

All business objects (except root and platform) must reference:

merchant="merchant(context)"

11. Platform Object​

The platform object is unique and does not reference other objects.

<platform
  name="ChildDevelopment"
  create_time="createTime()"
  last_update_time="updateTime()"
  _module_key="platform"
/>

12. Design Principles​

  • Except for root, every object must be associated with another object
  • Relationships are expressed via attributes, not nesting
  • KSML models relationships, not hierarchical trees

13. Validation Checklist​

  • Exactly one <root>
  • Each element defined once
  • No illegal nesting
  • No illegal id / version
  • All references use xxx()
  • Every element has _name, _module, _module_key
  • Constant objects declare _constant and _identifier

14. KSML Include Mechanism (<_include />)​

To support large-scale domain models, modularization, and reuse, KSML allows splitting models into multiple files and assembling them using the _include directive.

15. One-Sentence Summary​

KSML = Flat XML + Explicit Object References + Constant Finite Sets
for building stable, evolvable domain models. The _include mechanism is used to:

  • Split large KSML models into manageable files
  • Reuse common domain definitions (e.g. merchant, platform, employee)
  • Improve readability, maintainability, and team collaboration
  • Enable domain-level and module-level ownership

Sample


<root>
  <_include file="./platform.xml"/>
  <_include file="./merchant.xml"/>
  <_include file="./employee.xml"/>

  <_include file="./core/order.xml"/>
  <_include file="./core/customer.xml"/>
  <_include file="./core/invoice.xml"/>

  <_include file="./enum/order_status.xml"/>
  <_include file="./enum/payment_type.xml"/>
</root>