Common Configuration Sections

metadata

The metadata section provides basic identifying information about the brick.

metadata:
  # The unique id for the brick. Must be lower-case and of one of the following forms:
  id: github/profile
  
  # The semantic version of the brick, cf. https://semver.org/
  version: 0.0.1
  
  # A unique name for the brick
  name: Github Profile Reader
  
  # A longer description for the brick
  description: Read information from a Github user profile

metadata.id

A brick's id is its unique id in the PixieBrix ecosystem. An id is lower-case with letters a-z. An id may also include hyphens. A brick's id can also include a collection namespace. Collections are used to namespace bricks that provide similar functionality, or applicable in similar contexts (e.g., websites)

Public bricks id structure:

• <name>
• <collection>/<name>

Individuals and teams can also select an identifier that they can use to namespace their bricks. These bricks can be shared with other teams, or published publicly.

Private/shared bricks id structure:

• <@organization>/<collection>/<name>: e.g., @pixiebrix/browser/open-tab
• <@organization>/<name>: e.g., @pixiebrix/get
• <@username>/<collection>/<name>
• <@username>/<name>

The @local namespace is reserved for bricks created locally in the extension, and not shared anywhere

metadata.version

The version of the brick. Bricks are expected to use semantic versioning

In the future, we plan to automatically detect semver violations by comparing input and output schemas. For example, the following changes would indicate a semantic change:

• Input: a required property is added
• Output: a property is removed, or a required output is made optional

isAvailable

The isAvailable entry specifies when the brick is available and can be run. The isAvailable section is used in the following kinds of bricks:

• Foundations (kind: extensionPoint)
• Readers (kind: reader)
• Services (kind: service): determines which URLs the service is permitted to authenticate. The matchPatterns entry is tested against the API request URL.

isAvailable:
  
  # A match pattern or array of match patterns. The brick will be available if _any_ of the patterns match
  # If you want to match all URLs for a given domain, be sure to put a glob * at the end of the URL
  matchPatterns: https://github.com/*
  
  # This property does not apply to service configurations
  selectors: ".user-profile-sticky-bar"

isAvailable.matchPatterns

A match pattern or array of match patterns. The brick/service will be available if any of the patterns match.

For services, the match pattern is applied to the request URL. (i.e., as opposed to the URL where the bricks are being executed.)

For more examples of match patterns, see the Mozilla Developer Network documentation

isAvailable.selectors

Optionally provide one or more JQuery selectors that must be present on the page for the brick to be available.

For performance considerations of different selectors, see here: Optimize Selectors

inputSchema/outputSchema

PixieBrix uses JSON Schema to define the input/output specifications of bricks.

Because PixieBrix connects bricks by wiring inputs/outputs, the inputSchema and outputSchema sections will almost always a type: object as their top-level entry.

outputSchema:
  # optional: the version of the json-schema. Not currently used.
  $schema: https://json-schema.org/draft/2019-09/schema#

  type: object

  properties:

    myStringProp:
      type: string

    myNumberProp:
      type: number

    myEmailProp:
      type: string
      # https://json-schema.org/understanding-json-schema/reference/string.html#email-addresses
      format: email

    myArrayProp: 
      type: array
      items:
        type: number

    # entries can be nested
    myArrayOfObjects:
      type: array
      items:
        type: object
        properties:
          itemField:
            type: string

 # You can optionally list which properties on the object must be present
 # https://json-schema.org/understanding-json-schema/reference/object.html#required-properties
 required:
   - myArrayOfObjects
   - myNumberProp

Block references

$ref	Description
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 references

To require a specific service in an inputSchema, use the service ref pattern: https://app.pixiebrix.com/schemas/services/<service>. During validation, the existence of the service will be checked.

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