{"id":22799980,"url":"https://github.com/dadi/api-validator","last_synced_at":"2025-03-30T19:17:38.849Z","repository":{"id":57105403,"uuid":"153759879","full_name":"dadi/api-validator","owner":"dadi","description":"A module for validating DADI API documents","archived":false,"fork":false,"pushed_at":"2019-08-29T10:58:07.000Z","size":64,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-03-08T04:04:42.678Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dadi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-19T09:36:24.000Z","updated_at":"2020-07-30T12:59:29.000Z","dependencies_parsed_at":"2022-08-21T03:00:32.970Z","dependency_job_id":null,"html_url":"https://github.com/dadi/api-validator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadi","download_url":"https://codeload.github.com/dadi/api-validator/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365644,"owners_count":20765549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-12T07:10:42.359Z","updated_at":"2025-03-30T19:17:38.646Z","avatar_url":"https://github.com/dadi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API validator\n\n\u003e A module for validating DADI API documents\n\n[![npm (scoped)](https://img.shields.io/npm/v/@dadi/api-validator.svg?maxAge=10800\u0026style=flat-square)](https://www.npmjs.com/package/@dadi/api-validator)\n[![Coverage Status](https://coveralls.io/repos/github/dadi/api-validator/badge.svg?branch=master)](https://coveralls.io/github/dadi/api-validator?branch=master)\n[![Build Status](https://travis-ci.org/dadi/api-validator.svg?branch=master)](https://travis-ci.org/dadi/api-validator)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)\n\n## Overview\n\n[DADI API](https://dadi.cloud/api) is a high-performance RESTful layer designed in support of API-first development and COPE. With this module, you can perform validation of API documents within your project using the same logic as used by the DADI API core application.\n\n## Installation\n\nInstall the module via npm:\n\n```bash\nnpm install @dadi/api-validator\n```\n\n## Usage\n\nThe module exports a constructor method that expects the following named parameters relating to the instance of DADI API you're working with:\n\n- `i18nFieldCharacter`: the character used to represent the language variation of a field, as defined by the `i18n.fieldCharacter` configuration property (default: `:`)\n- `internalFieldPrefix`: the character used to prefix internal API fields, as defined by the `internalFieldPrefix` configuration property (default: `_`)\n\n```js\nconst Validator = require('@dadi/api-validator')\nconst myValidator = new Validator({\n  i18nFieldCharacter: ':',\n  internalFieldPrefix: '_'\n})\n```\n\nThe `Validator` class contains the following methods.\n\n### `validateAccessMatrix(matrix, fieldName)`\n\nValidates an access matrix. An optional `fieldName` can be supplied, which will be used in the error objects as the path of the field being validated.\n\n```js\n// Throws error:\n// \u003e [\n// \u003e   {\"field\": \"foo.invalidType\", \"code\": \"ERROR_INVALID_ACCESS_TYPE\"},\n// \u003e   {\"field\": \"foo.update.invalidKey\", \"code\": \"ERROR_INVALID_ACCESS_VALUE\"}\n// \u003e ]\nmyValidator.validateAccessMatrix(\n  {\n    create: true,\n    invalidType: true,\n    update: {\n      invalidKey: true\n    }\n  },\n  'foo'\n)\n\n// \u003e undefined\nmyValidator.validateAccessMatrix({\n  create: true,\n  delete: {\n    filter: {\n      someField: 'someValue'\n    }\n  }\n})\n```\n\n### `validateDocument({document, isUpdate, schema})`\n\nValidates a document against a collection schema. It returns a Promise that is resolved with `undefined` if no validation errors occur, or rejected with an array of errors if validation fails.\n\nIf `isUpdate` is set to `true`, the method does not throw a validation error if a required field is missing from the candidate document, because it is inferred that a partial update, as opposed to a full document, is being evaluated.\n\n```js\nconst mySchema = {\n  title: {\n    type: 'string',\n    validation: {\n      minLength: 10\n    }\n  }\n}\n\n// Rejected Promise:\n// \u003e [{\"field\": \"title\", \"code\": \"ERROR_MIN_LENGTH\"}]\nmyValidator\n  .validateDocument({\n    document: {\n      title: 'great'\n    },\n    schema: mySchema\n  })\n  .catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateDocument({\n  document: {\n    title: 'super amazing!'\n  },\n  schema: mySchema\n})\n```\n\n### `validateDocuments({documents, schema})`\n\nSame as `validateDocument` but expects an array of documents (as the `documents` property) and performs validation on each one of them, aborting the process once one of the documents fails validation.\n\n### `validateSchemaField(name, schema)`\n\nValidates a field schema, evaluating whether `name` is a valid field name and whether `schema` is a valid schema object.\n\n```js\n// Rejected Promise:\n// \u003e [{\"field\": \"fields.title\", \"code\": \"ERROR_MISSING_FIELD_TYPE\"}]\nmyValidator\n  .validateSchemaField('title', {\n    validation: {\n      minLength: 10\n    }\n  })\n  .catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateDocument({\n  type: 'string',\n  validation: {\n    minLength: 10\n  }\n})\n```\n\n### `validateSchemaFieldName(name)`\n\nValidates a field name.\n\n```js\n// Rejected Promise:\n// \u003e [{\"field\": \"fields.$no-good$\", \"code\": \"ERROR_INVALID_FIELD_NAME\"}]\nmyValidator.validateSchemaFieldName('$no-good$').catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateSchemaFieldName('all-good')\n```\n\n### `validateSchemaFields(fields)`\n\nValidates an entire `fields` object from a candidate collection schema. It runs `validateSchemaField` on the individual fields.\n\n```js\n// Rejected Promise:\n// \u003e [{\"field\": \"fields\", \"code\": \"ERROR_EMPTY_FIELDS\"}]\nmyValidator.validateSchemaFields({}).catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateSchemaFieldName({\n  title: {\n    type: 'string',\n    validation: {\n      minLength: 10\n    }\n  }\n})\n```\n\n### `validateSchemaSettings(settings)`\n\nValidates an entire `settings` object from a candidate collection schema.\n\n```js\n// Rejected Promise:\n// \u003e [{\"field\": \"fields.displayName\", \"code\": \"ERROR_INVALID_SETTING\"}]\nmyValidator\n  .validateSchemaSettings({\n    displayName: ['should', 'be', 'a', 'string']\n  })\n  .catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateSchemaSettings({\n  displayName: 'I am a string'\n})\n```\n\n### `validateValue({schema, value})`\n\nValidates a candidate value against a field schema. It returns a Promise that is resolved with `undefined` if no validation errors occur, or rejected with an error object if validation fails.\n\n```js\nconst mySchema = {\n  title: {\n    type: 'string',\n    validation: {\n      minLength: 10\n    }\n  }\n}\n\n// Rejected Promise:\n// \u003e {\"field\": \"title\", \"code\": \"ERROR_MIN_LENGTH\"}\nmyValidator\n  .validateField({\n    schema: mySchema,\n    value: 'great'\n  })\n  .catch(console.log)\n\n// Resolved Promise:\n// \u003e undefined\nmyValidator.validateDocument({\n  schema: mySchema,\n  value: 'super amazing!'\n})\n```\n\nWhen a `validationCallback` property is found in `schema`, it is used as a callback function that allows the user to supply additional validation logic that will be executed after the normal validation runs. This function can trigger a validation error by returning a rejected Promise.\n\n## License\n\nDADI is a data centric development and delivery stack, built specifically in support of the principles of API first and COPE.\n\nCopyright notice\u003cbr /\u003e\n(C) 2018 DADI+ Limited \u003csupport@dadi.cloud\u003e\u003cbr /\u003e\nAll rights reserved\n\nThis product is part of DADI.\u003cbr /\u003e\nDADI is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version (\"the GPL\").\n\n**If you wish to use DADI outside the scope of the GPL, please\ncontact us at info@dadi.co for details of alternative licence\narrangements.**\n\n**This product may be distributed alongside other components\navailable under different licences (which may not be GPL). See\nthose components themselves, or the documentation accompanying\nthem, to determine what licences are applicable.**\n\nDADI is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nThe GNU General Public License (GPL) is available at\nhttp://www.gnu.org/licenses/gpl-3.0.en.html.\u003cbr /\u003e\nA copy can be found in the file GPL.md distributed with\nthese files.\n\nThis copyright notice MUST APPEAR in all copies of the product!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapi-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadi%2Fapi-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapi-validator/lists"}