tymly-data-types

A work-in-progress library of data types often found in digital services.

Install

$ npm install @wmfs/tymly-data-types --save

Reference

The full list of 31 data-types currently defined by tymly-data-types is shown below.

• The chances are you'll never need to use all these in any one scenario (that's where domains and categories can help narrow things down).

Data Item Name	Title	Category	Domain(s)	Description
address	Address	text	location	A string denoting an address which could be used to send a letter.
appointmentTime	Appointment time	dateTime	general	A date and time, often originally defined for a point in the future, to express when a particular event should occur.
boolean	Boolean	choice	general	A general boolean value of true or false.
choice	Choice	choice	general	Use when a value should be taken from a known set, but no other data type is appropriate.
date	Date	dateTime	general	General-purpose type for expressing a particular date (without a time component).
dateOfBirth	Date of birth	dateTime	people	The date (no time portion) for expressing the date a person was born.
dateTime	Date/time	dateTime	general	General-purpose type for expressing a date and time.
email	Email	text	general, computing, person	Used to convey an email address.
ethnicity	Ethnicity	choice	people	Used to express the ethnicity of a person.
eventTime	Event time	dateTime	general	A date and time relating to when a particular event occurred.
frsCallsign	Callsign	text	fire	A unique code to identify a vehicle, officer or other asset.
fsecCode	FSEC code	choice	fire	A code to help categorise a premise (as defined by Home Office).
gender	Gender	choice	people	For describing a person's gender.
hostname	Hostname	text	computing	Used to convey an internet host name (RFC 5322).
idnHostname	IDN Hostname	text	computing	Used to convey an internationalized host name (RFC 5890).
integer	Integer	number	general	General-purpose type for expressing an integer value.
ipv4	IPv4	text	computing	Used to convey an IPv4 address.
ipv6	IPv6	text	computing	Used to convey an IPv6 address.
latLong	Latitude/Longitude	number	location	A pair of numbers denoting a point on the Earth's surface.
name	Person's name	text	people	A data-type for expressing a person's name.
notes	Notes	text	general	A data-item for expressing additional free-form notes often to provide deeper context for other data.
text	Text	text	general	General-purpose type for expressing textual data (a mixture of letters, numbers and symbols).
time	Time	dateTime	general	General-purpose type for expressing a time of day (without being related to any particular date).
title	Title	choice	people	Titles used to address people with (Miss, Mr. etc.)
uprn	UPRN	number	location, fire	Unique Property Reference Number as issued by Ordnance Survey as part of their gazetteer products.
uri	URI	text	general, computing	A universal resource identifier (URI) according to RFC3986.
usrn	USRN	number	location, fire	Unique Street Reference Number as issued by Ordnance Survey as part of their gazetteer products.
yesNo	Yes/No	choice	general	A data type to express a Yes/No response.
yesNoNa	Yes/No/Not Applicable	choice	general	A data type to express a 'Yes', 'No' or 'Not applicable' response.
yesNoOther	Yes/No/Other	choice	general	A data type to express a 'Yes', 'No' or 'Other' response.
yesNoUnknown	Yes/No/Unknown	choice	general	A data type to express a 'Yes', 'No' or 'Unknown' response.

Domains

Data items are grouped into specialist domains, this helps narrow lists of data-items to just those suitable to the business domain(s) being addressed:

• A single data-type can feature in multiple domains.
• Note the general domain is considered the "default". Without any explicit configuration (i.e. no specialist domains are provided via options), the various methods in the tymly-data-types API will return data items to just those within the general domain.

Domain Name	Title	Description
computing	Computing	Specialist data-types specific to computing.
fire	Fire Service	Data-types that are often used in the Fire and Rescue sector.
general	General	A set of general-purpose data types that can be used as a fallback if nothing more specific is available via other domains.
location	Location	Types often found when dealing with geo-spatial data.
people	People	Commonplace data-types relating to people (name, date of birth etc.)

Categories

As well as being grouped into one-or-more problem domains, each data-type is also assigned to a more functional category:

Category Name	Title	Description
choice	Choice	Data items that relate to a finite, known set of values.
dateTime	Date/time	Data items that relate to moments-in-time.
number	Number	Data items that relate to a numeric value.
ref	Reference	Data items whose value can relate to another entity
text	Text	Data items that can contain a mixture of letters, numbers and symbols.

API

getDomains(options)

Use the getDomains() method to get an array of available domains.

Options

Supply options as an object with the following keys (note all of this is optional):

Key	Description
filterString	If provided will help filter domains to just those matching the supplied string.
sort	Controls the order of that the domains will be returned. A string of either seq (default) or name.

getCategories(options)

Use the getCategories() method to grab a list of categories.

Options

Supply options as an object with the following keys (note all of this is optional):

Key	Description
filterString	If provided will help filter categories to just those matching the supplied string.
sort	Controls the order of that the categories will be returned. A string of either seq (default) or name.
domainRestriction	An array of strings denoting zero-or-more domain names. Only categories with one or more data-items in any of these domains will be returned. If no domainRestriction array is provided, then any categories used by data-items in just the general domain will be returned.

getDataTypes(options)

The main event, get a list of data-items as restricted by an object of optional options:

Key	Description
filterString	If provided will help filter data-items to just those matching the supplied string.
domainRestriction	Only data-types belonging to any of the domains provided will be returned. Use just as described in the getCategories() method. If omitted, will be restricted to data-types in the general domain.
category	An optional string. Only data-types belonging to the supplied category name will be returned.
sort	Controls the order of that the data items will be returned. A string of either seq (default) or name.

• This method returns an array of zero-or-more dataType objects. Take a look here to see the type of thing returned.

getDataTypeByName(dataTypeName)

Returns the specified data type.

getDataTypeNames()

Returns an array of data-type names.

getCategoryDefaultDataTypeNames()

Returns a key/value object where key is the name of a category and value is the name of a dataType considered the "default" for that category.

{
  "text": "text",
  "number": "integer",
  "dateTime": "dateTime",
  "choice": "choice"
}

getDataItemsByCategory(options)

Just like getDataTypes() but returns a key/value object where key is a category name and value is the associated array of data items.

Testing

$ npm test

Todo

• Make into an online database! :smiley:
• Modules (having everything in one big JSON file is a bit wrong).
• Introduce versioning solution
• Validation of domains, categories and data-types.
• Especially integrity checks (data items belong to valid domains/categories), JSON Schema based?

License

MIT