Schemas

In any micro service type of application, defining a contract between services is key to build a predictable, scalable and self documenting (!) system.

Schemas are used to describe the shape and validation of messages that are sent to and from a service.

This is done in Fruster by leveraging JSON schemas where each handler can (it is optional, but very much recommended) define a json schema for requests and responses.

Adding schemas to your service

There are three ways of adding schemas to your service:

1. Schemas as JSON files

All schemas in /lib/schemas folder will be picked up and parsed as schemas when the service starts.

The id in the schemas is used as key to reference the schema from subscribes.

Example:

{
  "id": "AddSystemRoleRequest",
  "description": "Request for adding a system role.",
  "additionalProperties": false,
  "properties": {
    "role": {
      "type": "string",
      "description": "The role name to add."
    },
    "scopes": {
      "type": "array",
      "description": "Scopes for the role.",
      "items": {
        "type": "string",
        "description": "The scopes"
      }
    }
  },
  "required": ["role"]
}

Example of subscribe that uses the schema:

bus.subscribe({
  // ...
  requestSchema: "AddSystemRoleRequest",
});

2. Schemas as modules

JSON schemas does not necessarily need to be plain JSON, it can be defined as a module such as this:

export default {
  id: "AddSystemRoleRequest",
  description: "Request for adding a system role.",
  additionalProperties: false,
  properties: {
    role: {
      type: "string",
      description: "The role name to add.",
    },
    scopes: {
      type: "array",
      description: "Scopes for the role.",
      items: {
        type: "string",
        description: "The scopes",
      },
    },
  },
  required: ["role"],
};

Example of subscribe that uses the schema (note that in these cases we can reference the module):

import AddSystemRoleRequest from "../schemas/AddSystemRoleRequest";

bus.subscribe({
  // ...
  requestSchema: AddSystemRoleRequest,
});

3. Schemas as TypeScript interfaces

👷‍♀️ This feature is currently in beta, more information will follow.

By defining typescript interfaces, fruster bus will at runtime compile those into JSON schemas.

This is handy and a time saver as models often is needed anyways in your application and by letting those same interfaces be parsed to JSON schemas it is one less thing to keep track of.