@financial-times/biz-ops-schema-sdk

This library provides a means to consume the Biz Ops schema so that applications can automatically keep up to date with changes to it.

Installation and usage

npm install @financial-times/biz-ops-schema-sdk

The package exports a singleton instance, and once initialised, @financial-times/biz-ops-schema can be required multiple times in the application. It should be initialised once and once only per application. It also exports a reference to the underlying SDK class, but this is only exposed for use by other packages' integration tests.

Configuring

Exposes an .init() method, which accepts the following options (which can also be set using environment variables). In most cases it's recommended to use environment variables as this means .init() does not need to be called explicitly.

• sourceUrl | BIZ_OPS_SCHEMA_URL - Url the sdk will poll to retrieve new versions of the schema.

• sourceDirectory | BIZ_OPS_SCHEMA_DIRECTORY - absolute path to a directory that contains schema files as yaml.

• sourceData - a javascript object containing a complete Treecreeper schema. Generally only used in tests

• includeTestDefinitions | BIZ_OPS_SCHEMA_TEST=true|false - (default: false) a flag to indicate whether to use schema definitions that are defined in a /test subdirectory. This is typically only needed when publishing/republishing the schema

Initialising

Calling await schema.ready() will automatically call schema.init() (if not already called) with whatever options can be derived from the environment. This is the preferred way to initialise, but schema.init() can be called manually when it is useful to control the exact point at which schema data is fetched. In particular, schema.init() must be called with appropriate options when running on the client side.

Troubleshooting

It's important that an application installs only one copy of biz-ops-schema. If an application installs other packages, e.g. biz-ops-view, that install biz-ops-schema-sdk then a) make sure the versions of biz-ops-schema-sdk specified in their package.json files are compatible b) if multiple copies of biz-ops-schema-sdk exist in node_modules despite compatibility, run npm prune or delete your node_modules and run a fresh install.

A note on lambdas

Previous versions of the schema sdk required explicitly specifying whether a polling or stale on refresh strategy for updating was used. This is now deduced from the environment the sdk is running in and does not need to be set explicitly.

The only difference between usage is that in a lambda compared schema.ready() shoudl be awaited at the beginning of each handler, whereas in a persistent server it's fine to await it once on app startup.

SDK API

Once initialised the sdk exposes a number of methods to access schema data:

Schema access APIs

All methods use an internal caching mechanism, which is flushed whenever the schema updates. For this reason

• It is safe to call these methods many times because the complex transformation of values is only executed on the first invocation
• It is an antipattern to store the result of any invocation in a variable for any non synchronous period of time - this may result in incorrect reading or writing of data
• There is an onChange(func) method that can be used to attach handlers that will be called every time the schema changes

getType(type, options)

Get an object defining the structure of a given type. The following transforms will be executed on the raw yaml data.

• if no pluralName field is defined, it will be generated
• any named stringPatterns will be converted to validation functions

The full object structure returned by getType() can been seen here

options

• withRelationships [default: true]: Include the relationships for the type, expressed as graphql property definitions.
• groupProperties [default: false]: Each property may have a fieldset attribute. Setting groupProperties: true removes the properties object from the data, and replaces it with fieldsets, where all properties are then grouped by fieldset
• includeMetaFields [default: false]: Determines whether to include metadatafields (prefixed with _) in the schema object returned
• includeSyntheticFields [default: true]: Determines whether to include synthetic fields (those using a custom cypher statement) in the schema object returned
• useMinimumViableRecord [default: false]: If groupProperties is true, this will put any fields defined as being part of the minimum viable record (see model spec) together in a single fieldset

getTypes(options)

Get an array of objects defining the structure of all types. All options for getType are supported and determine the internal structure of each type. Additionally, the following options can be specified:

• grouped [default: false] - determines whether to return the types as a flat array, or an object grouping types in categories. Each category specifies a label, description and list of types.

getEnums(options)

Retrieves an array of key:value objects defining the acceptable values of an enum

options

• withMeta: wrap the enum in an object which also has metadata about the enum (e.g. 'description'.). In this case, the actual enum options will be in a options property

validateTypeName(typeName)

Validates that a type of the given name exists in the schema

validateCode (typeName, code)

Validates that a code string matches the validation pattern defined for codes for the given type

validatePropertyName ( propertyName )

Validates that a string is a valid name for an attribute (i.e. camelCase)

validateProperty(typeName, propertyName, propertyValue)

Validates that the value of a property for a given type is valid

normalizeTypeName

Should be used when reading a type name from e.g. a url. Currently is a noop, but will allow consistent rolling out of more forgiving url parsing in future if necessary

The methods below are unimplemented

describeGraphqlQuery(query)

Decorates a graphql query with metadata from the schema

describeGraphqlResult(query, result)

describeRestApiResult(type, result, options)