Reference

A Reference component represents any external resource. One of the central fields of the Reference object is the uri, which describes the location of the referenced resource. If the resource has been resolved, its content is stored in the fields value and cache.

It is worth noting that a resolved Reference can also have References in its content,and that circular references are possible, e.g. a reference to a schema describing a User could have a friends field that contain a reference to the User schema. Therefore a depth of evaluation can be used to describe how many references should be followed. For instance, with a depth of 2, in our User scenario, we would get an evaluated schema containing a User, its friends, and then friends of each friends, stored inside the friends field of each friend.

The purpose of the cache field is to store resolutions for different depths, so as to not evaluate that depth again. By design, the value field is therefore equivalent to the content of the cache field of depth 0.

Import

/* if in src/ */
import { Reference } from './models/Reference'

Interface

Reference extends Immutable.Record using the following pattern:

class Reference extends Immutable.Record({
    uri: null,
    resolved: false,
    value: null,
    description: null
})

Fields

Reference.uri

• Reference.uri is a unique resource identifier used to refer to the missing content. It expects a String that can be validated against the Reference.validate method. Required.

Reference.resolved

• Reference.resolved is a Boolean flag describing whether the Reference has already been resolved.

Reference.value

• Reference.value contains the resolved value.

Reference.description

• Reference.description expects a description of the content referred to by the Reference.uri

Methods

Reference is an abstract class. Class extending it MUST implement these functions.

Reference.validate

• Reference.validate(uri) returns a Boolean describing whether the input uri conforms to the constraints set by the Reference class.

Reference.evaluate

• Reference.evaluate(references, depth = 0) returns the evaluated content of the Reference.value, at depth resolution level, using the ReferenceContainer references as a base for following internal references. Any reference that's missing from references is kept as is. If Reference.value is null, this will also return null.

Example

Please note that this example is abstract, and is there purely to represent the different interactions with Reference. The data may be non-sensical.

import references from './samples/references-examples'
import referenceContainers from './samples/referenceContainers-examples'

import { Reference } from './models/Reference'

let reference = new Reference({
    uri: 'http://www.ietf.org/rfc/rfc2396.txt',
    resolved: true,
    value: 'Uniform Resource Identifier (URI): Generic Syntax ...',
    description: 'This document contains the RFC defining a URI'
})

reference = reference
    .set('uri', '27:a3:a0:6f:1f:d6')
    .set('resolved', false)
    .set('value', {
        some: 'data',
        ref: new Reference({
            uri: 'http://www.ietf.org/rfc/rfc2396.txt'
        })
    })
    .set('description', 'description of what we can fetch from this uri')


/* These methods are abstract and will throw */
let valid = reference.validate('http://www.ietf.org/rfc/rfc2396.txt')
reference = reference
   .evaluate(referenceContainers[0], 3)
   .evaluate(referenceContainers[1], 1)