Best Practice > Naming of MSOs and Properties

Intended audience: developers administrators

AO Platform: 4.4

Overview

This topic proposes naming conventions for the Managed Semantic Objects (MSOs) and their fields (MSO Properties) to ensure clarity, consistency, and ease of interpretation by users. The Names of MSOs and their MSO Properties can all be found within the MSO Composer.

MSO Name (singular and plural)

MSO Property Names

Why Is This Important

The objective is to avoid the most common mistakes by creating names that are descriptive, meaningful, and aligned with business requirements, ensuring they are LLM-compliant and user-friendly, and ultimately ensuring the best possible outcome for using the Ontology as part of any Easy Answers solution created with the AO Platform.

By adhering to these naming conventions, you create a structured, intuitive framework that enhances clarity, consistency, and LLM compliance. This systematic approach not only facilitates user understanding and reduces ambiguity but also strengthens alignment with business requirements. Furthermore, the incorporation of the LLM Ontology Descriptions, see Best Practice > Describing the Ontology, allows a deeper context-driven interpretation of MSOs and their MSO Properties, optimizing the utility and relevance of generated responses.

General Naming Principles

• Descriptiveness: Names should be clear, informative, and avoid abbreviations to ensure readability.

• Semantic Richness: Include key details such as units, data types, or status indicators to add clarity.

• Consistency: Use uniform patterns across all MSOs and fields for easy understanding.

• Full Words: Avoid abbreviations to reduce ambiguity. For instance, instead of abbreviations like cust, use full words like Customer.

• Hierarchy and Relationships: Indicate relationships or categories, where relevant.

What To Do

Edit the MSOs and their MSO Properties using the MSO Composer. MSO Names are available on the General Properties page, and MSO Property Names are available on the MSO Properties page.

Use the following rules and best practices to create the most optimal Ontology possible.

MSO Naming Conventions

Each MSO name should accurately reflect its purpose within the system.

• Content Focus: Use names that describe the main entity or concept the MSO represents.

  • Examples: customer_profile, order_transaction, product_inventory.

• Relationship Indicators: For MSOs representing relationships, include the related entities.

  • Examples: customer_order_relationship, user_account_linkage.

MSO Property Naming Conventions

• Context-Rich Names: Include the entity or category within the name.

  • Examples: first_name, total_amount.

• Units of Measurement: Specify units to avoid confusion.

  • Examples: weight_kilograms, total_usd.

• Data Type Indication: Specify data types IF they add clarity.

  • Examples: sales_amount, creation_date, but it’s unnecessary to use is_open_boolean or balance_number.

• Temporal Information: Clearly indicate if a field represents a specific time or duration.

  • Examples: date_of_purchase, processing_duration_days, account_creation_datetime.

• Calculated Fields: Use suffixes for derived or calculated fields IF they add clarity.

  • Examples: total_spend_percentage - if there’s a total_spend_amount property.

LLM-Friendly MSO and Property Names

• Avoid database-style abbreviations. Use descriptive, business-friendly names.

• Examples: Use Customer instead of cust, First Name instead of fName, and avoid complex relationship field names like i_cust by using descriptive names, such as customer.

Unique Property Naming

• As much as possible, avoid using the same name for Ontology, MSOs, and any MSO Properties. Especially, do not name an MSO and any of its Properties the same. It will just make it much harder, sometimes impossible, for an LLM to interpret a question correctly due to the ambiguities created.

• Example: In a Meter MSO, avoid naming a property meter.

Singular Naming with Accurate Plural Forms

• Use singular forms for MSO names and verify that plural names in the MSO properties are correct, as auto-generated plurals may sometimes be inaccurate.

• Any linguistic terms for either MSO itself or associated properties should also be added on same MSO to remove any ambiguities, eg. add synonyms such as “errors”, “faults”, and “problems” to the Meter Issues MSO to ensure that no matter how the user expresses the question relating to problems with Meters, the correct MSO will be found and question correctly interpreted.

Naming Convention Examples for Common Entities

References

• MSO - General Properties

• MSO - Properties

Contact App Orchid | Disclaimer