Let’s talk about element and attribute naming

This article isn’t about naming conventions. My opinion on naming conventions is that they are necessary both for end-users and developers to assist in making a system understandable and navigable. But I don’t have an opinion on what the best naming convention is other than it doesn’t exist. Whether a naming convention uses spaces, underscores, Proper Case, camelCase really doesn’t matter. What does matter is that the naming convention is consistently and universally applied within a given system?

What this topic is about is rules for illegal (or potentially troublesome) characters which should inform and be a founding principal of any naming convention.

We will consider characters that should (must) be avoided for three distinct scenarios:

• Object names
• Element names
• Attribute names (a special case of element names)

All TM1 objects; dimensions, cubes, processes, chores (and application entries, cube views, dimension subsets) are stored as file system objects in the data directory. Therefore, any characters not allowed in directory paths or file names need to be excluded from TM1 object names. As TM1 can run on Linux or Windows OS we need to consider illegal characters for both operating systems, of which Windows has the most restrictions. Characters not allowed in Windows folder or file names are as follows:

• < (less than)
• > (greater than)
• : (colon)
• ” (double quote)
• / (forward slash)
• (backslash)
• | (pipe)
• ? (question mark)
• * (asterisk)

Additionally, the Ascii null character and all non-printable Ascii control characters from 1 – 31 are prohibited and would cause object creation to fail if included as part of an object name. Windows also has a number of reserved names and namespaces which should be avoided. You can find a good resource here on Microsoft Developer Network discussing file naming rules and limitations.

As well as file system exclusions, as TM1 developers we should also exclude any special characters that have special meaning in TM1 as these can also cause issues. There is a considerable overlap with forbidden Windows characters so let’s just consider the additional characters we should exclude due to their special meaning in TM1:

• ‘ (single-quote / apostrophe, the TM1 quote character)
• ; (semi-colon, line terminator in Rules & TI)
• , (comma)
• @ (at sign, TM1 string operator qualifier)
• ! (exclamation mark, element wildcard in TM1 Rules)
• ~ (tilda, not operator in TM1 Rules)
• % (percent, or operator in TM1 Rules, variable substitution in Expand function, html usage)
• + (plus sign, addition operations, MDX concatenation & union operator)
• – (minus sign, subtraction operations)
• & (ampersand, and operator in Rules & TI)
• = (equal sign)
• [] (opening & closing square-brace, used in Rules & MDX)
• {} (opening & closing curly-brace, MDX set identifier, control object identifier)
• (non-breaking space, Ascii code 160)

Note:    In addition to the illegal OS path and file characters, from the above list of special characters TM1 only explicitly forbids using the first 3 (single-quote, semi-colon, comma) in object names. However, it is certainly good practice to avoid using any of the above characters which have special meaning in TM1 in object names. You can find a good IBM reference discussing TM1 special characters here. Although the non-breaking space has no special meaning in TM1 the reason it should be avoided is a simple one, namely to avoid confusion and trouble-shooting headaches.

Unlike object names, TM1 supports the use of all Unicode characters in an element name. In fact, TM1 does not explicitly prohibit the use of any character as part of an element name including non-printable characters. Although non-printable characters are technically allowed in element names they should never be used for reasons which should be obvious due to the confusion this would cause users, developers and administrators alike.

Due to interaction with rules, MDX and scripting languages the following characters should be avoided at all costs as the first character of an element name “ ‘ @ ! + – [ ] { } % due to the likelihood of causing expressions to fail in MDX or compile errors in TM1 Rules. However, generally, all rules used for avoiding characters in object names should also be applied to element names as well. Put simply special characters are best avoided as these can cause unintended and unexpected consequences.

We should consider that any element name may be part of a filter and may be used in a subset of view name during an automated process (and therefore become part of a file name), in which case any restriction applied to object names should also be applied to elements. Moreover, with the ever-increasing use of the Restful API and browser-based UIs using MDX and html we want to avoid breaking queries due to element names or creating any requirement to use escape characters.

Although principal element names (and alias values) will often be loaded from source systems we should consider cleansing of element name metadata to avoid any characters with a potential to cause issues.

In addition to the special characters already named we should also consider avoiding in any element names any characters which might be used as delimiters within filter or string arrays. Especially in any model where the bedrock library is in use where use of such delimited strings is extremely common. Also the TM1 server is now much more open than previously with many connections to many 3^rd party libraries and languages now possible via the Rest API, many of which may have further restrictions on acceptable characters.

TM1 may be case and space insensitive but the OData standards and TM1’s Restful API are not. The TM1 Restful API observes the OData specification which has a limitation of only accepting alpha-numeric Ascii characters and underscore. All special characters and spaces should be avoided.

Therefore, to avoid issues querying attribute values via the Rest API we need to be even more restrictive in naming attributes than in naming elements (even though in fact attribute names are just elements). Attribute names should contain only characters:

• A – Z      (characters 65 – 90)
• a – z       (characters 97 – 122)
• 0 – 9      (characters 48 – 57)
• _             (underscore, character 95)