Joi Key Extensions

Joi Key Extensions provides extensions to the Joi validation library that allow validation of:

• Foreign key style relationships, where a value must be a reference to a value elsewhere in an object tree. Unlike the Joi built in built in ref validation, it can traverse arrays to look up references
• Primary key values, validating that a set of keys are unique within an array of objects

fkExtension

Usage

1npm install --save joi-key-extensions

1const VanillaJoi = require('joi');
2const { fkExtension } = require('joi-key-extensions');
3
4// add the extension to Joi
5const Joi = VanillaJoi.extend(fkExtension.string);
6
7const makeSchema = Joi.object({
8  makeId: Joi.string(),
9  name: Joi.string(),
10});
11
12const modelSchema = Joi.object({
13  modelId: Joi.string(),
14  name: Joi.string(),
15  makeId: Joi.string()
16    // define the foreign key reference
17    .fk('makes.[].makeId'),
18});
19
20const schema = Joi.object({
21  makes: Joi.array().items(makeSchema),
22  models: Joi.array().items(modelSchema),
23});
24
25console.log('Examples with valid data');
26
27const data = {
28  makes: [
29    { makeId: 'ford', name: 'Ford' },
30    { makeId: 'mazda', name: 'Mazda' },
31  ],
32  models: [
33    { modelId: 'laser', name: 'Laser', makeId: 'ford' },
34    { modelId: 'familia', name: 'Familia', makeId: 'mazda' },
35  ],
36};
37
38console.log('Validating whole object tree');
39let validationResult = schema.validate(data, {
40  context: {
41    data, // pass whole object tree as context.data
42    schema, // pass schema of whole object tree as context.schema
43  },
44});
45
46console.log(validationResult.error);
47// null - no error
48
49console.log('Validating one model out of the object tree');
50validationResult = modelSchema.validate(data.models[0], {
51  context: {
52    data,
53    schema,
54  },
55});
56
57console.log(validationResult.error);
58// null - no error
59
60console.log('Examples with invalid data');
61
62data.models[0].makeId = 'fnord';
63
64console.log('Validating whole object tree');
65validationResult = schema.validate(data, {
66  context: {
67    data,
68    schema,
69  },
70});
71
72console.log(validationResult.error);
73// { ValidationError: child "models" fails because
74// ["models" at position 0 fails because
75//   [child "makeId" fails because
76//     ["makeId" "fnord" could not be found as a reference to "makes.[].makeId"]]]...
77
78console.log('Validating one model out of the object tree');
79validationResult = modelSchema.validate(data.models[0], {
80  context: {
81    data,
82    schema,
83  },
84});
85
86console.log(validationResult.error);
87// { ValidationError: child "makeId" fails because
88// ["makeId" "fnord" could not be found as a reference to "makes.[].makeId"]...
89
90

API

Joi.string().fk(args)

Joi.date().fk(args)

Joi.number().fk(args)

Requires that a field value must be a reference to a value elsewhere in the object tree.

In the simplest case args is a string with a dot seperated list of object fields, with search across an array identified by square brackets ([]).

E.g. Joi.number().fk('species.[].speciesId') requires that the value must match the speciesId field in one of the items in the species array field.

The extension also supports multi-part foreign keys. E.g.

1const animalSchema = Joi.object({
2  animalId: Joi.string(),
3  // genusId must correspond to an element in the genus array, matching on the genusId field
4  genusId: Joi.string().fk('genus.[].genusId'),
5  // speciesId must correspond to an element in the species array belonging to the genus element
6  // identified by the genusId field
7  speciesId: Joi.string().fk('genus.[].species.[].speciesId', { parentFieldName: 'genusId' }),
8});

Refer to __tests__ /fkExtension.text.js for more examples

pkExtension

Usage

1npm install --save joi-key-extensions

1const VanillaJoi = require('joi');
2const { pkExtension } = require('joi-key-extensions');
3
4// add the extension to Joi
5const Joi = VanillaJoi
6  .extend(pkExtension.number)
7  .extend(pkExtension.array);
8
9const countrySchema = Joi.object({
10  countryId: Joi.number().pk(),
11  countryName: Joi.string(),
12});
13
14const schema = Joi.object({
15  countries: Joi.array()
16    .items(countrySchema)
17    .uniqueOnPks(),
18});
19
20const data = {
21  countries: [
22    { countryId: 1, countryName: 'Estonia' },
23    { countryId: 2, countryName: 'Uruguay' },
24  ],
25};
26
27console.log('Example with valid data');
28
29let validationResult = schema.validate(data, {
30  context: {
31    data, // pass whole object tree as context.data
32    schema, // pass schema of whole object tree as context.schema
33  },
34});
35
36console.log(validationResult.error);
37// null - no error
38
39console.log('Example with invalid data');
40
41data.countries.push({ countryId: 1, countryName: 'Fiji' });
42
43validationResult = schema.validate(data, {
44  context: {
45    data,
46    schema,
47  },
48});
49
50console.log(validationResult.error);
51// null - no error
52// { ValidationError: child "countries" fails because
53// ["countries" There is a duplicate value at path countries for keys {"countryId":1}]
54

API

Joi.string().pk()

Joi.number().pk()

Joi.date().pk()

Identifies that the field is part of a primary key (composed of one or more fields).

Joi.array().uniqueOnPks()

Requires that the elements of the array must be unique with respect to their primary key fields