{"id":21401433,"url":"https://github.com/spoonx/stix-schema","last_synced_at":"2025-03-16T16:16:25.950Z","repository":{"id":34410527,"uuid":"178537296","full_name":"SpoonX/stix-schema","owner":"SpoonX","description":"🔌 Stix module that validates parameters for your requests using joi.","archived":false,"fork":false,"pushed_at":"2022-12-06T15:21:32.000Z","size":146,"stargazers_count":1,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-25T20:39:58.506Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpoonX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-30T09:17:05.000Z","updated_at":"2019-06-27T09:13:16.000Z","dependencies_parsed_at":"2023-01-15T06:55:54.814Z","dependency_job_id":null,"html_url":"https://github.com/SpoonX/stix-schema","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpoonX%2Fstix-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpoonX%2Fstix-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpoonX%2Fstix-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpoonX%2Fstix-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpoonX","download_url":"https://codeload.github.com/SpoonX/stix-schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243893897,"owners_count":20364919,"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-11-22T15:27:44.480Z","updated_at":"2025-03-16T16:16:25.925Z","avatar_url":"https://github.com/SpoonX.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stix-schema\n\nA [stix](https://stixjs.io/) module and middleware that adds schema validation for your requests using [joi](https://github.com/hapijs/joi).\n\n## Installation\n\n1. `yarn add stix-schema`.\n2. Add the module to your project\n\n```ts\nimport SchemaModule from 'stix-schema';\n\nexport const modules: ModuleManagerConfigInterface = [\n  SchemaModule,\n  Application,\n];\n```\n\n## Summary\n\n- **Cool feature alert:** When combined with [stix-swagger](https://github.com/SpoonX/stix-swagger) you get schemas generated for your swagger docs out of the box.\n- Schema validation will run immediately after the router is done.\n- If validation fails, stix-schema responds to the user with a clientError _(bad request)_ of `invalid_parameters` and sends along the details of the failed validations.\n- If validation is successful, the parameters get set on `ctx.state.params` for consumption elsewhere.\n- If you use stix-gates as well, it's good to know that gates run **after** stix-schema validation.\n\n## Usage\n\nCreate a config in the `schema` namespace. Example configuration **config/schema.ts:**\n\n```ts\nimport { AbstractActionController } from 'stix';\nimport { SchemaConfig, SchemaRuleset } from 'stix-schema';\nimport { UserController } from '../src/Controller';\nimport { NewUser } from '../src/Schema/User';\n\nexport const schema: SchemaConfig = {\n  schemas: new Map\u003ctypeof AbstractActionController, SchemaRuleset\u003e([\n    [UserController, {\n      register: { body: NewUser },\n    }],\n  ]),\n};\n```\n\nWith this in place, every request that triggers `UserController.register` will be validated against the NewUser schema first.\n\n### Example schema:\n\nA schema must export an object wit ha `name` and the `schema`.\n\n```ts\nimport Joi from 'joi';\n\nexport const NewUser = {\n  name: 'NewUser',\n  schema: Joi.object().keys({\n    username: Joi.string().alphanum().min(3).max(30).required(),\n    password: Joi.string().regex(/^[a-zA-Z0-9]{3,30}$/),\n    email: Joi.string().email({ minDomainAtoms: 2 }),\n  }),\n};\n```\n\n### Using the params\n\nStix-schema will take the result of the validation and when successful put the params on `ctx.state.params`.\n\n```ts\nexport class UserController extends AbstractActionController {\n  public async register (ctx): Promise\u003cResponse\u003e {\n    const { username, email, password } = ctx.state.params;\n    // Go nuts!\n  }\n}\n```\n\nNow you can assume the data has been set and focus on logic.\n\n## Configuration\n\nThere are a couple of configuration options at your disposal of which the one you'll use most is `schemas` _(as seen in the example above)_.\n\nThese are the defaults:\n\n```ts\nexport const schema: SchemaConfig = {\n  merge: true,\n  defaultOptions: { allowUnknown: true, stripUnknown: true },\n};\n```\n\n### Schemas\n\nSchemas is a mapping of actions to schemas.\n\n```ts\nimport { AbstractActionController } from 'stix';\nimport { SchemaConfig, SchemaRuleset } from 'stix-schema';\nimport { UserController } from '../src/Controller';\nimport { NewUser, ProfileSearch, LanguageString, Translations } from '../src/Schema/User';\n\nexport const schema: SchemaConfig = {\n  schemas: new Map\u003ctypeof AbstractActionController, SchemaRuleset\u003e([\n    [UserController, {\n      // Validate the body. (e.g. for post requests)\n      // This also shows you can use options on schema rules.\n      register: { body: NewUser, options: { allowUnknown: false } },\n\n      // Validate the query. (e.g. for get requests)\n      profile: { query: ProfileSearch },\n\n      // Validate both the query and the body (e.g. posting for a specific language)\n      profile: { query: LanguageString, body: Translations },\n    }],\n  ]),\n};\n```\n\n### Merge\n\nMerge tells stix-schema to merge the results of `query` and `body` into one object.\n\n**Merge false:**\n\n```ts\nconst result = {\n  query: { bar: 'bar' },\n  body: { foo: 'foo' },\n};\n```\n\n**Merge true:**\n\n```ts\nconst result = {\n  bar: 'bar', \n  foo: 'foo',\n};\n```\n\nThis is generally the desired behaviour and is therefor the default.\n\n### defaultOptions\n\nThese are the default options used for schema validation. They're used when a `schema` entry in the config doesn't provide it's own options. Generally you'll want to allow additional params to be sent along, but simply ignore them. This is the default behaviour:\n\n- Unknown properties are allowed\n- Unknown properties get stripped\n\nIf you do need access to unknown properties, you can set `stripUnknown` to false or access them directly from `ctx.request.query` or `ctx.request.body`.\n\n## FAQ\n\nNot really an FAQ as such... It's more a list of questions I'm expecting.\n\n### Why use Map\n\nBecause this follows the same philosophy as stix: modules should provide [IoC](https://en.wikipedia.org/wiki/Inversion_of_control). In other words, any module that decides to use stix-schema should allow the user to override configuration options. \n\nYou can have multiple controllers with the same name, so the controller itself is used as the key to make it very explicit.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoonx%2Fstix-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspoonx%2Fstix-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoonx%2Fstix-schema/lists"}