Formats

Formats can be applied to properties in Data, and if specified will allow for data to be pre-formatted when emitted from the Data services. The format service relies upon two main libraries for its formatting - momentjs and numeraljs.

The basic use of formats is to provide a single format rule identified by a code which will typically apply to a particular culture.

{
    "type": "DATE",
    "code": "date",
    "label": "standard date",
    "description": "standard date",
    "formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "dd.MM.yyyy"
        }
    ]
}

In the above case, a simple dd.MM.yyyy format code for dates is used which is applicable to data requested for users from en-GB. When applied to particular date data points, those dates will become formatted in this way when requested by a user in GB in English.

There are more sophisticated ways of formatting data too, allowing things such as prefixes and suffixes.

{
    "type": "Currency",
    "code": "ccy",
    "label": "standard ccy",
    "description": "standard ccy",
    "formatRules": [
        {
            "culture": "en-US",
            "formatCode": "0,0.00",
            "prefix": "$",
            "suffix": "USD"
        }
    ]
}

Furthermore, there is the ability to apply conditionals.

Ltgte

In the example below, a less than, greater than or equal to operator has been used. In this instance, if the value breaches a certain threshold, a different format can be used. This is useful with very large numbers.

The format for the ltgte conditionals object is as follows:

"conditionals":[
    {
        "type":"ltgte",
        "boundary": number,
        "lt": string,
        "gte": string,
    }
]

In the example below, numbers over 1,000,000 would show as 1M.

{
    "type": "Currency",
    "code": "ccy",
    "label": "standard ccy",
    "description": "standard ccy",
    "formatRules": [
        {
            "culture": "en-US",
            "formatCode": "0,0.00",
            "conditionals": [
                {
                    "type": "ltgte",
                    "boundary": 1000000,
                    "lt": "0,0.00",
                    "gte": "0.0a"
                }
            ]
        }
    ]
}

Divideby

A divideby conditional will divide the number presented by a specific number before formatting.

The format for the divideby conditionals object is as follows:

"conditionals":[
    {
        "type":"divideby",
        "by": number
    }
]

Example

{
    "type": "percentage",
    "code": "perc",
    "label": "standard %",
    "description": "standard %",
    "formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0%",
            "conditionals": [
                {
                    "type": "divideby",
                    "by": 100
                }
            ]
        }
    ]
}

labelOverride

A labelOverride conditional will change the format of a particular value based on the label it has associated with it. This is only used in allocations, statistics or historical datasets and their associated property definitions.

The format for the labelOverride conditionals object is as follows:

"conditionals":[
    {
        "type":"labelOverride",
        "labelrules":[
            {
                "label": string,
                "format": string
            }
        ]
    }
]

Example

{
    "type": "percentage",
    "code": "perc",
    "label": "standard %",
    "description": "standard %",
    "formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0%",
            "conditionals": [
                {
                    "type": "labelOverride",
                    "labelrules": [
                        {
                            "label": "Average Duration",
                            "format": "0,0"
                        }
                    ]
                }
            ]
        }
    ]
}

valueOverride

A valueOverride conditional will change the actual returned value of a particular item based on the original value it has associated with it. This is useful for overriding zero values. This is only used in allocations or statistics and their associated property definitions.

The format for the valueOverride conditionals object is as follows:

"conditionals":[
    {
        "type": "valueOverride",
        "valueRules":[
            {
                "value": string,
                "format": string
            }
        ]
    }
]

Example

{
    "type": "percentage",
    "code": "perc",
    "label": "standard %",
    "description": "standard %",
    "formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0%",
            "conditionals": [
                {
                    "type": "valueOverride",
                    "valueRules": [
                        {
                            "value": "0",
                            "format": "No Value Here!!!"
                        }
                    ]
                }
            ]
        }
    ]
}

rounding

A rounding format rule will set the rounding method used. There are two rounding methods round_up and away_from_zero with round_up being the default if no rounding is specified. round_up will round a positive number away from zero and a negative number closer to zero while away_from_zero will round a positive and a negative number away from zero.

The default rounding method will round 3.795 to 3.80 and -3.795 to -3.79

"formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0,0.00",
        }
    ]

The following rounding method will round 3.795 to 3.80 and -3.795 to -3.80

"formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0,0.00",
            "rounding": "away_from_zero"
        }
    ]

Example

{
    "type": "NUMB",
    "code": "number_1dp",
    "label": "1 dp format",
    "description": "Standard number, 1dp",
    "formatRules": [
        {
            "culture": "en-GB",
            "formatCode": "0,0.00",
            "rounding": "away_from_zero"
        }
    ]
}