@wmfs/tymly-data-types NPM

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.)

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?