Standards

Writing good data definitions

Having a clear and consistent definition of the data you are exchanging will make it easier for the community to send the right data, first time

These principles were influenced by ISO 11179, part 4. You should have a look if you’re interested writing good definitions

Define in the singular

Example: Article Number

Not so good definition Reference number identifying articles
Better A reference number that describes an article
Why? The ‘not so good’ definition uses the plural word “articles”. This makes it ambiguous since it could imply that article numbers can apply to more than one article

Don’t negate

Example: Freight Cost Amount

Not so good definition Costs which are not related to packing, documentation, loading, unloading and insurance
Better The cost incurred by a shipper moving goods from one place to another
Why? The ‘not so good’ definition doesn’t specify what is actually in the definition

Use phrases

Example: Agent Name

Not so good definition Representative
Better The name of a party authorised to act on behalf of another party
Why? ‘Representative’ is a near-synonym of the item’s name. It doesn’t actually explain anything.

Example: Country Name

Not so good definition Name of a country
Better The commonly known, short name that identifies a country
Why? Simply restating the name in sentence form doesn’t describe the concept that is a short name, vs. an expanded or long Name

Example: Mailing Address Country

Not so good definition The mailing address country name is the name of the country where the mail piece is delivered.
Better The name of the country where a mail piece is delivered
Why? Repeating the item’s name in a sentence doesn’t add anything that clarifies the item’s intent. There is also no reason to use more words than needed.

Only use commonly understood abbreviations

Example: Tide Height

Not so good definition The vertical distance from MSL to a specific tide level
Better The vertical distance from mean sea level (MSL) to a specific tide level
Why? MSL may not be a commonly understood abbreviation and some members may need to refer to other sources to determine what it represents

Don’t embed other definitions

Example: Sample Type Code

Not so good definition The code identifying the kind of sample collected. A sample is a small specimen taken for testing. It can either be an actual sample for testing, or a quality control surrogate sample. A quality control sample is a surrogate sample taken to verify results of actual samples
Better The code identifying the kind of sample
Why? “quality control surrogate sample” should be defined as a separate item

Stick to the essentials

Example: Invoice Amount

Not so good definition The total sum of all chargeable items mentioned on an invoice, taking into account deductions on one hand, such as allowances and discounts, and additions on the other hand, such as charges for insurance, transport, handling, etc
Better The total sum charged on an invoice
Why? There is a lot on extra information that isn’t relevant

Don’t overprescribe

Example: Consignment Loading Sequence Number

Not so good definition The number indicating the sequence in which consignments are loaded in a truck
Better The number indicating the sequence in which consignments are loaded for transport
Why? Consignments can be transported by more than trucks.

Be precise

Example: Country Code

Not so good definition The code that represents a country
Better The alphabetic code assigned by the International Standards Organisation (ISO) 3166-1 to represent a country
Why? Country Codes are assigned by various standards and organisations. Without specifying which standard is being used, interoperability issues are likely to occur

Be concise

Example: Character Set Name

Not so good definition The name given to the set of phonetic or ideographic symbols in which data is encoded, for the purpose of this metadata registry, or, as used elsewhere, the capability of systems hardware and software to process data encoded in one or more scripts
Better The name given to the set of phonetic or ideographic symbols in which data is encoded
Why? Don’t include unnecessary information that doesn’t actually describe what the item is

Stand alone

Example: School Location City Name

Not so good definition See “school site”
Better The name of the city where a school is situated
Why? Don’t rely on other definitions to understand the meaning of items

Don’t be restrictive

Example: Income Tax Gross Amount

Not so good definition The amount of income tax payable on the company’s annual return before the allowance of any rebates/tax offsets or credits
Better The amount of income tax payable before the allowance of any rebates/tax offsets or credits
Why? By being overly restrictive the item can only be used in one context, forcing other similar items to be created

Avoid circular reasoning

Example: Employee and Employee ID Number

Employee definition The number assigned to an Employee
Employee ID Number definition The person corresponding to the an employee ID number
Why? Each definition refers to the other for it’s meaning. Neither definition actually provides any meaning.
Back