📖
PixieBrix Documentation
📐

JSON Schema

PixieBrix uses JSON Schema for specifying the shapes of inputs and outputs. These appear in the inputSchema and outputSchema sections of a configuration file. (Read more at

.

We use JSON Schema for a few purposes:

  • UI Generation: the forms in the tool are generated from the JSON Schema
  • Documentation: know which variables are available at a given point in a mod
  • Debugging: having a schema facilities detecting which bricks are misbehaving. For example, if a brick has valid input, but it's output doesn't match it schema, we know there's likely a bug in the brick.

If you're coming from the Javascript world, these are similar to React's prop-types or schema validators such as Yup

Learning Resources

Special String Formats for PixieBrix

In JSON Schema, properties of type string also support a format directive. PixieBrix has special handling for the following formats:

  • selector: when rendering an form input, includes a selector button so the user can choose an element from the page using point-and-click interface

Special Refs

JSON Schema supports $ref as a way of referencing another schema. PixieBrix uses $ref as a way of extending JSON Schema to support non-JSON types.

Brick Refs

$refDescription
https://app.pixiebrix.com/schemas/block#
A reference to a block: a reader, renderer, effect, or transform
https://app.pixiebrix.com/schemas/renderer#
A reference to a renderer block
https://app.pixiebrix.com/schemas/effect#
A reference to an effect block
https://app.pixiebrix.com/schemas/reader#
A reference to a reader block
https://app.pixiebrix.com/schemas/transformer#
A reference to a transform block

Service Refs

To require a specific service in an inputSchema, use the service ref pattern: https://app.pixiebrix.com/schemas/services/<service>.

When saving the brick, PixieBrix will verify that the service exists. At runtime, PixieBrix will enforce that the provided service configuration is for the service and is a valid configuration.

For example, the service property below will match a service configuration for the nytimes/api service.

inputSchema:
  type: object
  properties:
    service:
      $ref: "https://app.pixiebrix.com/schemas/services/nytimes/api"
		organizationName:
	    type: string
	    description: The name of the company to search for
  required:
    - service
    - organizationName`

Service Secrets

Secrets (e.g., API keys) can be marked using $ref: https://app.pixiebrix.com/schemas/key#. Secrets can only be referenced in the authentication section.

Secrets are not made available to bricks. Additionally, secrets configured for team service configurations are not shared with team members. Configured team services with secrets are proxied through PixieBrix to authenticate the request

inputSchema:
  type: object
  properties:
    apiKey:
      $ref: https://app.pixiebrix.com/schemas/key#
  required:
    - apiKey
authentication:
  headers:
    Authorization: Token {{apiKey}}

Twitter