This page outlines naming conventions for configuration. Conventions are not hard-and-fast rules – they won’t stop the application running, but rather are a set of agreed best practises to make creating and maintainign configuration easier.
Format
This page outlines naming conventions for configuration. There are various sections and examples, but they can be summarised by the high-level rules outlined in the sections below.
camelCase
camelCase is the default format and used for all configuration elements and values, other than the items outlined in the kebab-case section below. Also, domain names, domain attribute names and component names all start with a capital letter.
kebab-case
kebab-case is a format that it quite easy to read. It tends to come across as less "codie" and is used in some cases to make the configuration value more user-friendly, or where conventions have arisen through interactions with other frameworks (e.g. the Vue UI layer).
The following configuration item values should use kebab-case:
- Any custom tags such as platform, ui, search, etc. – both the tag names and any option attributes
- Service form item
valueelementnameattribute values
Namespaced values
A configuration item’s value is considered “namespaced” if it can contain full stops delineating logical groups. The groups are ordered from most to least significant from left to right.
The term "namespace" can have various meanings but in the context of configuration item values namespacing is the method of using full stop characters (.) to separate the value into logical groups.
As namespaces break the value into significant logical groups and separate words within these groups follow the camelCase format.
For example a text key for an error message relating to the value being too long for the "Name" attribute within the "ComponentX" component might have a text key of "componentX.name.message.tooLong", which is defined by four different logical groups separated by the full stop character (.). Also notice the groups are ordered from most significant to least significant from left to right.
Since namespacing is for significant
Configuration values that tend to be namespaced are:
- Localised text key
keyattribute values (thus error codes too) - Additional property
keyattribute values - Certain Data Constraint
nameattribute values
Namespaced configuration values always use camelCase, never kebab-case, as the combination of hyphens (-) and full stop (.) characters can be quite jarring.
Some other good examples may be:
| Namespaced value example | Description |
|---|---|
| privateCompany.service.title | The title text key for the private company registration business service |
| company.countryOfOrigin | Text key prefix value for a “CountryOfOrigin” attribute relating to companies |
| company.countryOfOrigin.label | The text key for the label for a “CountryOfOrigin” attribute relating to companies |
| telephone.number.help | The text key for the help label for a “Number” attribtue within the Telephone component |
Error codes
Error codes, which are also used as text keys for the error message, can be used for any message level (i.e. info, warn or error). Regardless of the level the text keys should all include a group attribute value of "message". They should also include the namespace ".message" after the component name and domain/attribute namespaces, prior to the namespace describing the message condition itself.
For example for an error message relating to the DisplayName attribute within the EntityName component:
- entityName.displayName.message.tooLong
See the text keys section below for more examples.
Text keys
A localised text item for a label for a Line1 attribute element within an Address domain record, with no other clarifying characterstics:
- address.line1.label
If the localised text was was specific to a type of address, say a physical address, then it should have the form:
- address.physical.line1.label
If it’s also restricted to a certain company type, say a local company, then it should be one of the following depending on how you’d prefer to distinguish a local company from other company types:
- localCompany.address.physical.line1.label
- company.local.address.physical.line1.label
If you wanted an error code specific to this same attribute, say a length restriction for when it’s too short, then it would be one of:
- localCompany.address.physical.line1.message.tooShort
- company.local.address.physical.line1.message.tooShort
Components
Text keys, or text key prefixes, without components should start with the component name, except starting with a lower case letter. For example the text key (or prefixes) without a component called "MyComponent" should start "myComponent." e.g. "myComponent.attributeX".
