# @axway/api-builder-schema

> A singleton module for loading custom schemas and resolving them to json-schema docs

Latest version **5.0.0** (published 2022-09-09) · SEE LICENCE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @axway/api-builder-schema
pnpm add @axway/api-builder-schema
yarn add @axway/api-builder-schema
bun add @axway/api-builder-schema
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2022-09-09 |
| First published | 2022-09-09 |
| Weekly downloads | 0 |
| License | SEE LICENCE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 16 |
| Dependencies | 5 |
| Unpacked size | 36.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Axway |
| Maintainers | nkeranova, axway-npm, cb1kenobi, jamie.peabody, awam, bladedancer, axway_darnaudov, ddimonov-axway, neon-axway, vchauhan, mdimitrova, pdzhorev, axway_alasdair, pltod2, npetrovski-axway, pbozhkovaxway, mbonchev-axway, axway-vertex, cdobrica |
| Keywords | amplify, api-builder, axway |

## Links

- npm: https://www.npmjs.com/package/@axway/api-builder-schema
- Homepage: https://platform.axway.com
- npm.io page: https://npm.io/package/@axway/api-builder-schema

## Dependencies (5)

- [ajv](https://npm.io/package/ajv.md) ^6.12.5
- [uri-js](https://npm.io/package/uri-js.md) ^3.0.2
- [@axway/json-refs](https://npm.io/package/@axway/json-refs.md) ^4.0.0
- [strict-uri-encode](https://npm.io/package/strict-uri-encode.md) ^2.0.0
- [@axway/json-pointer](https://npm.io/package/@axway/json-pointer.md) ^0.7.0

## Recent versions

- 5.0.0 (latest) — 2022-09-09

## README

# @axway/api-builder-schema

A singleton module for loading custom schemas and resolving them to json-schema docs

# API Reference

**Example** *(Quick start)*  
```javascript
 const schemas = require('axway-schema');
 schemas.add('./schemas/foo.json')
	  .add('./schemas/bar.json', 'schema://myservice/bar')
	  .add('./schemas/swagger-v2.0.json')
	  .loadSync();
 schemas.get('schema:///foo');
 schemas.validate('schema:///foo', foo);
 schemas.get('schema:///foo/myservice/bar');
 schemas.validate('schema:///foo/myservice/bar', bar);
 schemas.get('http://swagger.io/v2/schema.json#');
 schemas.validate('http://swagger.io/v2/schema.json#', swagger);
 schemas.dereference(swagger);
 schemas.dereference(swagger, { target: '#/definitions' });
 schemas.dereference(swagger, { target: '#/definitions', rename: (id) => { return 'foo'; } });
```
<a name="module_axway-schema..AxwaySchema"></a>

### axway-schema~AxwaySchema
A schema manager.

**Kind**: inner class of [<code>axway-schema</code>](#module_axway-schema)  
**Access**: public  

* [~AxwaySchema](#module_axway-schema..AxwaySchema)
    * [new AxwaySchema()](#new_module_axway-schema..AxwaySchema_new)
    * [.setLogger(logger)](#module_axway-schema..AxwaySchema+setLogger)
    * [.add(item, [defaultId])](#module_axway-schema..AxwaySchema+add) ⇒ <code>AxwaySchema</code>
    * [.register(schema)](#module_axway-schema..AxwaySchema+register) ⇒ <code>AxwaySchema</code>
    * [.loadSync()](#module_axway-schema..AxwaySchema+loadSync) ⇒ <code>AxwaySchema</code>
    * [.clear()](#module_axway-schema..AxwaySchema+clear) ⇒ <code>AxwaySchema</code>
    * [.exists(id)](#module_axway-schema..AxwaySchema+exists) ⇒ <code>boolean</code>
    * [.get([id])](#module_axway-schema..AxwaySchema+get) ⇒ <code>object</code>
    * [.validate(id, obj)](#module_axway-schema..AxwaySchema+validate) ⇒ <code>string</code>
    * [._updateRef(doc, ref, refpath, encodedRef)](#module_axway-schema..AxwaySchema+_updateRef)
    * [.dereference(doc, [options])](#module_axway-schema..AxwaySchema+dereference) ⇒ <code>object</code>
    * [.getErrorString(errors, objectType)](#module_axway-schema..AxwaySchema+getErrorString) ⇒ <code>string</code>

<a name="new_module_axway-schema..AxwaySchema_new"></a>

#### new AxwaySchema()
Constructs a schema manager.  The instance is a singleton.

<a name="module_axway-schema..AxwaySchema+setLogger"></a>

#### axwaySchema.setLogger(logger)
Sets the Logger

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| logger | <code>Logger</code> | A logger. |

<a name="module_axway-schema..AxwaySchema+add"></a>

#### axwaySchema.add(item, [defaultId]) ⇒ <code>AxwaySchema</code>
Adds an item to be loaded later by calling
[loadSync](#module_axway-schema..AxwaySchema+loadSync).
The `item` can be a `string`, in which case it is a schema file, and an optional `defaultId`
will be used for the `id` if the file does not have an `id`.  If the file does not have an
`id` and no `defaultId` is supplied, the function will throw.

If the `item` is an object, it is a valid schema that has an `id` defined so that
it can be referenced later.  In this case, `defaultId` is ignored.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>AxwaySchema</code> - The [AxwaySchema](AxwaySchema) object.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| item | <code>string</code> \| <code>object</code> | The item to add (a filename or schema). |
| [defaultId] | <code>string</code> | The item id if one not supplied. |

**Example** *(Add a schema)*  
```javascript
 const schemas = new AxwaySchema();
 schemas.add('./schema1.json');
 schemas.add('./schema2.json', 'schema://service/myapp/schema2.json');
 schemas.add({id: 'http://axway.com/schemas/user.json'});
```
<a name="module_axway-schema..AxwaySchema+register"></a>

#### axwaySchema.register(schema) ⇒ <code>AxwaySchema</code>
Registers a global schema that will persist across calls to
[clear](#module_axway-schema..AxwaySchema+clear) operations.  Schemas registered with
the same `id` will generate a warning but will be ignored.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>AxwaySchema</code> - The [AxwaySchema](AxwaySchema) object.  

| Param | Type | Description |
| --- | --- | --- |
| schema | <code>object</code> | The schema. |

<a name="module_axway-schema..AxwaySchema+loadSync"></a>

#### axwaySchema.loadSync() ⇒ <code>AxwaySchema</code>
Loads all schemas previously added with calls to
[add](#module_axway-schema..AxwaySchema+add).

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>AxwaySchema</code> - The [AxwaySchema](AxwaySchema) object.  
**Access**: public  
**Example** *(Load schemas)*  
```javascript
 const schemas = new AxwaySchema();
 schemas
	  .add('./schema1.json');
	  .add('./schema2.json', 'service');
	  .loadSync());
```
<a name="module_axway-schema..AxwaySchema+clear"></a>

#### axwaySchema.clear() ⇒ <code>AxwaySchema</code>
Clears all schemas and resets state.  All registered schema will be
automatically re-added on next load.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>AxwaySchema</code> - The [AxwaySchema](AxwaySchema) object.  
**Access**: public  
<a name="module_axway-schema..AxwaySchema+exists"></a>

#### axwaySchema.exists(id) ⇒ <code>boolean</code>
Tests whether or not a schema is loaded, identified by `id`.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>boolean</code> - True if the schema exists.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| id | <code>string</code> | The schema identifier to test. |

<a name="module_axway-schema..AxwaySchema+get"></a>

#### axwaySchema.get([id]) ⇒ <code>object</code>
Gets a schema by `id`.  If `id` is not supplied, all schemas are returned.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>object</code> - Returns a schema identified by `id`.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| [id] | <code>string</code> | The schema identifier. |

<a name="module_axway-schema..AxwaySchema+validate"></a>

#### axwaySchema.validate(id, obj) ⇒ <code>string</code>
Validates an object `obj` against a schema previously added with
[add](#module_axway-schema..AxwaySchema+add) or
[register](#module_axway-schema..AxwaySchema+register)
and identified by `id`, or if `id` is a JSON schema object, `obj` is validated
against that.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>string</code> - Returns an error string when not valid, undefined otherwise.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| id | <code>string</code> \| <code>object</code> | The schema identifier or object. |
| obj | <code>\*</code> | The object to validate. |

<a name="module_axway-schema..AxwaySchema+_updateRef"></a>

#### axwaySchema.\_updateRef(doc, ref, refpath, encodedRef)
Updates the reference with its encoded equivalent.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  

| Param | Type | Description |
| --- | --- | --- |
| doc | <code>Object</code> | the doc to be updated |
| ref | <code>Object</code> | reference details |
| refpath | <code>string</code> | the path to be replaced |
| encodedRef | <code>string</code> | the new path |

<a name="module_axway-schema..AxwaySchema+dereference"></a>

#### axwaySchema.dereference(doc, [options]) ⇒ <code>object</code>
Dereferences non-local references in the supplied document.  The supplied
document is not modified.  All non-local references (e.g `schema://`) will
be replaced with the corresponding loaded schema.  If schema are not found,
an error will be thrown.

If `options.target` is not supplied, then references are expanded inline.  If
`options.target` is supplied, then references are expanded in the location specified
by `options.target` and any existing reference updated to point to the new target.
For example, if the `options.target` is `#/definitions`, then the schema will be
expanded to `$.definitions` with the name of the schema the trailing component
(basename) of its `id`, or if `options.rename` is supplied, the name
returned by that.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>object</code> - Returns a document with `schema://` references expanded.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| doc | <code>object</code> | A document |
| [options] | <code>object</code> | Options |
| [options.target] | <code>string</code> | A target |
| [options.rename] | <code>targetRenameCallback</code> | A callback to rename schema |

<a name="module_axway-schema..AxwaySchema+getErrorString"></a>

#### axwaySchema.getErrorString(errors, objectType) ⇒ <code>string</code>
The ajv.errorsText is actually not very good.

**Kind**: instance method of [<code>AxwaySchema</code>](#module_axway-schema..AxwaySchema)  
**Returns**: <code>string</code> - A formatted error string.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| errors | <code>array</code> | ajv errors object |
| objectType | <code>string</code> | The name of the object type that was validated |

<a name="module_axway-schema..targetRenameCallback"></a>

### axway-schema~targetRenameCallback ⇒ <code>string</code>
Callback function to rename a target when used as a
[dereference](#module_axway-schema..AxwaySchema+dereference) target.
For example, if your id is "schema://svc.foo/bar", then `bar` will be written
to the dereference target as `bar`.  If you want to rename `bar`, then use
this function.

**Kind**: inner typedef of [<code>axway-schema</code>](#module_axway-schema)  
**Returns**: <code>string</code> - Return the renamed target.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| id | <code>id</code> | The schema id. |


## Building

```bash
npm run build
```

## Author

Axway <support@axway.com> https://axway.com

## License

This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: [https://support.axway.com/en/auth/general-conditions](https://support.axway.com/en/auth/general-conditions); EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.

---
_Source: https://npm.io/package/@axway/api-builder-schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._