API.md

json-refs

Various utilities for JSON References (http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and JSON Pointers (https://tools.ietf.org/html/rfc6901).

• json-refs
  • .JsonRefsOptions : object
  • .RefDetailsFilter ⇒ boolean
  • .RefPostProcessor ⇒ object
  • .RefPreProcessor ⇒ object
  • .ResolvedRefDetails : UnresolvedRefDetails
  • .ResolvedRefsResults : object
  • .RetrievedRefsResults : ResolvedRefsResults
  • .RetrievedResolvedRefsResults : object
  • .UnresolvedRefDetails : object
  • .clearCache()
  • .decodePath(path) ⇒ Array.<string>
  • .encodePath(path) ⇒ Array.<string>
  • .findRefs(obj, [options]) ⇒ Object.<string, (UnresolvedRefDetails|undefined)>
  • .findRefsAt(location, [options]) ⇒ Promise.<RetrievedRefsResults>
  • .getRefDetails(obj) ⇒ UnresolvedRefDetails
  • .isPtr(ptr, [throwWithDetails]) ⇒ boolean
  • .isRef(obj, [throwWithDetails]) ⇒ boolean
  • .pathFromPtr(ptr) ⇒ Array.<string>
  • .pathToPtr(path, [hashPrefix]) ⇒ string
  • .resolveRefs(obj, [options]) ⇒ Promise.<ResolvedRefsResults>
  • .resolveRefsAt(location, [options]) ⇒ Promise.<RetrievedResolvedRefsResults>

json-refs.JsonRefsOptions : object

The options used for various JsonRefs APIs.

Kind: static typedef of json-refs
Properties

Name	Type	Default	Description
filter	string | Array.<string> | function	"function () {return true;}"	The filter to use when gathering JSON References (If this value is a single string or an array of strings, the value(s) are expected to be the type(s) you are interested in collecting as described in getRefDetails. If it is a function, it is expected that the function behaves like RefDetailsFilter.)
includeInvalid	boolean	false	Whether or not to include invalid JSON Reference details (This will make it so that objects that are like JSON Reference objects, as in they are an Object and the have a $ref property, but fail validation will be included. This is very useful for when you want to know if you have invalid JSON Reference definitions. This will not mean that APIs will process invalid JSON References but the reasons as to why the JSON References are invalid will be included in the returned metadata.)
loaderOptions	object		The options to pass to PathLoader~load
location	string	"root.json"	The location of the document being processed (This property is only useful when resolving references as it will be used to locate relative references found within the document being resolved. If this value is relative, path-loader will use window.location.href for the browser and process.cwd() for Node.js.)
refPreProcessor	RefPreProcessor		The callback used to pre-process a JSON Reference like object (This is called prior to validating the JSON Reference like object and getting its details)
refPostProcessor	RefPostProcessor		The callback used to post-process the JSON Reference metadata (This is called prior filtering the references)
resolveCirculars	boolean	false	Whether to resolve circular references
subDocPath	string | Array.<string>	"[]"	The JSON Pointer or array of path segments to the sub document location to search from

json-refs.RefDetailsFilter ⇒ boolean

Simple function used to filter out JSON References.

Kind: static typedef of json-refs
Returns: boolean - whether the JSON Reference should be filtered (out) or not

Param	Type	Description
refDetails	UnresolvedRefDetails	The JSON Reference details to test
path	Array.<string>	The path to the JSON Reference

json-refs.RefPostProcessor ⇒ object

Simple function used to post-process a JSON Reference details.

Kind: static typedef of json-refs
Returns: object - the processed JSON Reference details object

Param	Type	Description
refDetails	UnresolvedRefDetails	The JSON Reference details to test
path	Array.<string>	The path to the JSON Reference

json-refs.RefPreProcessor ⇒ object

Simple function used to pre-process a JSON Reference like object.

Kind: static typedef of json-refs
Returns: object - the processed JSON Reference like object

Param	Type	Description
obj	object	The JSON Reference like object
path	Array.<string>	The path to the JSON Reference like object

json-refs.ResolvedRefDetails : UnresolvedRefDetails

Detailed information about resolved JSON References.

Kind: static typedef of json-refs
Properties

Name	Type	Description
circular	boolean	Whether or not the JSON Reference is circular (Will not be set if the JSON Reference is not circular)
fqURI	string	The fully-qualified version of the uri property for UnresolvedRefDetails but with the value being relative to the root document
missing	boolean	Whether or not the referenced value was missing or not (Will not be set if the referenced value is not missing)
value	*	The referenced value (Will not be set if the referenced value is missing)

json-refs.ResolvedRefsResults : object

The results of resolving the JSON References of an array/object.

Kind: static typedef of json-refs
Properties

Name	Type	Description
refs	ResolvedRefDetails	An object whose keys are JSON Pointers (fragment version) to where the JSON Reference is defined and whose values are ResolvedRefDetails
resolved	object	The array/object with its JSON References fully resolved

json-refs.RetrievedRefsResults : ResolvedRefsResults

An object containing the retrieved document and detailed information about its JSON References.

Kind: static typedef of json-refs
Properties

Name	Type	Description
value	object	The retrieved document

json-refs.RetrievedResolvedRefsResults : object

An object containing the retrieved document, the document with its references resolved and detailed information about its JSON References.

Kind: static typedef of json-refs
Properties

Name	Type	Description
refs	UnresolvedRefDetails	An object whose keys are JSON Pointers (fragment version) to where the JSON Reference is defined and whose values are UnresolvedRefDetails
resolved	object	The array/object with its JSON References fully resolved
value	object	The retrieved document

json-refs.UnresolvedRefDetails : object

Detailed information about unresolved JSON References.

Kind: static typedef of json-refs
Properties

Name	Type	Description
def	object	The JSON Reference definition
error	string	The error information for invalid JSON Reference definition (Only present when the JSON Reference definition is invalid or there was a problem retrieving a remote reference during resolution)
uri	string	The URI portion of the JSON Reference
uriDetails	object	Detailed information about the URI as provided by URI.parse.
type	string	The JSON Reference type (This value can be one of the following: invalid, local, relative or remote.)
warning	string	The warning information (Only present when the JSON Reference definition produces a warning)

json-refs.clearCache()

Clears the internal cache of remote documents, reference details, etc.

Kind: static method of json-refs

json-refs.decodePath(path) ⇒ Array.<string>

Takes an array of path segments and decodes the JSON Pointer tokens in them.

Kind: static method of json-refs
Returns: Array.<string> - the array of path segments with their JSON Pointer tokens decoded
Throws:

• Error if the path is not an Array

See: https://tools.ietf.org/html/rfc6901#section-3

Param	Type	Description
path	Array.<string>	The array of path segments

json-refs.encodePath(path) ⇒ Array.<string>

Takes an array of path segments and encodes the special JSON Pointer characters in them.

Kind: static method of json-refs
Returns: Array.<string> - the array of path segments with their JSON Pointer tokens encoded
Throws:

• Error if the path is not an Array

See: https://tools.ietf.org/html/rfc6901#section-3

Param	Type	Description
path	Array.<string>	The array of path segments

json-refs.findRefs(obj, [options]) ⇒ Object.<string, (UnresolvedRefDetails|undefined)>

Finds JSON References defined within the provided array/object.

Kind: static method of json-refs
Returns: Object.<string, (UnresolvedRefDetails|undefined)> - an object whose keys are JSON Pointers (fragment version) to where the JSON Reference is defined and whose values are UnresolvedRefDetails.
Throws:

• Error when the input arguments fail validation or if options.subDocPath points to an invalid location

Param	Type	Description
obj	array | object	The structure to find JSON References within
[options]	JsonRefsOptions	The JsonRefs options

Example

// Finding all valid references
var allRefs = JsonRefs.findRefs(obj);
// Finding all remote references
var remoteRefs = JsonRefs.findRefs(obj, {filter: ['relative', 'remote']});
// Finding all invalid references
var invalidRefs = JsonRefs.findRefs(obj, {filter: 'invalid', includeInvalid: true});

json-refs.findRefsAt(location, [options]) ⇒ Promise.<RetrievedRefsResults>

Finds JSON References defined within the document at the provided location.

This API is identical to findRefs except this API will retrieve a remote document and then return the result of findRefs on the retrieved document.

Kind: static method of json-refs
Returns: Promise.<RetrievedRefsResults> - a promise that resolves a RetrievedRefsResults and rejects with an Error when the input arguments fail validation, when options.subDocPath points to an invalid location or when the location argument points to an unloadable resource

Param	Type	Description
location	string	The location to retrieve (Can be relative or absolute, just make sure you look at the options documentation to see how relative references are handled.)
[options]	JsonRefsOptions	The JsonRefs options

Example

// Example that only resolves references within a sub document
JsonRefs.findRefsAt('http://petstore.swagger.io/v2/swagger.json', {
    subDocPath: '#/definitions'
  })
  .then(function (res) {
     // Do something with the response
     //
     // res.refs: JSON Reference locations and details
     // res.value: The retrieved document
  }, function (err) {
    console.log(err.stack);
  });

json-refs.getRefDetails(obj) ⇒ UnresolvedRefDetails

Returns detailed information about the JSON Reference.

Kind: static method of json-refs
Returns: UnresolvedRefDetails - the detailed information

Param	Type	Description
obj	object	The JSON Reference definition

json-refs.isPtr(ptr, [throwWithDetails]) ⇒ boolean

Returns whether the argument represents a JSON Pointer.

A string is a JSON Pointer if the following are all true:

• The string is of type String
• The string must be empty, # or start with a / or #/

Kind: static method of json-refs
Returns: boolean - the result of the check
Throws:

• error when the provided value is invalid and the throwWithDetails argument is true

See: https://tools.ietf.org/html/rfc6901#section-3

Param	Type	Default	Description
ptr	string		The string to check
[throwWithDetails]	boolean	false	Whether or not to throw an Error with the details as to why the value provided is invalid

Example

// Separating the different ways to invoke isPtr for demonstration purposes
if (isPtr(str)) {
  // Handle a valid JSON Pointer
} else {
  // Get the reason as to why the value is not a JSON Pointer so you can fix/report it
  try {
    isPtr(str, true);
  } catch (err) {
    // The error message contains the details as to why the provided value is not a JSON Pointer
  }
}

json-refs.isRef(obj, [throwWithDetails]) ⇒ boolean

Returns whether the argument represents a JSON Reference.

An object is a JSON Reference only if the following are all true:

• The object is of type Object
• The object has a $ref property
• The $ref property is a valid URI (We do not require 100% strict URIs and will handle unescaped special characters.)

Kind: static method of json-refs
Returns: boolean - the result of the check
Throws:

• error when the provided value is invalid and the throwWithDetails argument is true

See: http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

Param	Type	Default	Description
obj	object		The object to check
[throwWithDetails]	boolean	false	Whether or not to throw an Error with the details as to why the value provided is invalid

Example

// Separating the different ways to invoke isRef for demonstration purposes
if (isRef(obj)) {
  // Handle a valid JSON Reference
} else {
  // Get the reason as to why the value is not a JSON Reference so you can fix/report it
  try {
    isRef(str, true);
  } catch (err) {
    // The error message contains the details as to why the provided value is not a JSON Reference
  }
}

json-refs.pathFromPtr(ptr) ⇒ Array.<string>

Returns an array of path segments for the provided JSON Pointer.

Kind: static method of json-refs
Returns: Array.<string> - the path segments
Throws:

• Error if the provided ptr argument is not a JSON Pointer

Param	Type	Description
ptr	string	The JSON Pointer

json-refs.pathToPtr(path, [hashPrefix]) ⇒ string

Returns a JSON Pointer for the provided array of path segments.

Note: If a path segment in path is not a String, it will be converted to one using JSON.stringify.

Kind: static method of json-refs
Returns: string - the corresponding JSON Pointer
Throws:

• Error if the path argument is not an array

Param	Type	Default	Description
path	Array.<string>		The array of path segments
[hashPrefix]	boolean	true	Whether or not create a hash-prefixed JSON Pointer

json-refs.resolveRefs(obj, [options]) ⇒ Promise.<ResolvedRefsResults>

Finds JSON References defined within the provided array/object and resolves them.

Kind: static method of json-refs
Returns: Promise.<ResolvedRefsResults> - a promise that resolves a ResolvedRefsResults and rejects with an Error when the input arguments fail validation, when options.subDocPath points to an invalid location or when the location argument points to an unloadable resource

Param	Type	Description
obj	array | object	The structure to find JSON References within
[options]	JsonRefsOptions	The JsonRefs options

Example

// Example that only resolves relative and remote references
JsonRefs.resolveRefs(swaggerObj, {
    filter: ['relative', 'remote']
  })
  .then(function (res) {
     // Do something with the response
     //
     // res.refs: JSON Reference locations and details
     // res.resolved: The document with the appropriate JSON References resolved
  }, function (err) {
    console.log(err.stack);
  });

json-refs.resolveRefsAt(location, [options]) ⇒ Promise.<RetrievedResolvedRefsResults>

Resolves JSON References defined within the document at the provided location.

This API is identical to resolveRefs except this API will retrieve a remote document and then return the result of resolveRefs on the retrieved document.

Kind: static method of json-refs
Returns: Promise.<RetrievedResolvedRefsResults> - a promise that resolves a RetrievedResolvedRefsResults and rejects with an Error when the input arguments fail validation, when options.subDocPath points to an invalid location or when the location argument points to an unloadable resource

Param	Type	Description
location	string	The location to retrieve (Can be relative or absolute, just make sure you look at the options documentation to see how relative references are handled.)
[options]	JsonRefsOptions	The JsonRefs options

Example

// Example that loads a JSON document (No options.loaderOptions.processContent required) and resolves all references
JsonRefs.resolveRefsAt('./swagger.json')
  .then(function (res) {
     // Do something with the response
     //
     // res.refs: JSON Reference locations and details
     // res.resolved: The document with the appropriate JSON References resolved
     // res.value: The retrieved document
  }, function (err) {
    console.log(err.stack);
  });