Schemas

Schemas are used to define and validate data structures in Bubblescript. They are defined in YAML files with the .yml extension and provide runtime validation for (declared) tasks and functions. If an input or output value does not match its schema definition, a runtime error will be raised, helping catch data inconsistencies early in development.

Defining Schemas

Schemas are defined in YAML files with names ending in schemas.yml. These files can be placed in the root directory or in subdirectories. All schema files are merged into the single @schemas constant.

Example schema definition:

# schemas.yml
user:
  type: object
  additionalProperties: false
  properties:
    name:
      type: string
    age:
      type: number
  required:
    - name

Schema files can be placed in any directory and will be automatically merged. However, duplicate schema definitions will raise an error. For example:

# schemas.yml
user:
  type: object
  properties:
    name:
      type: string

# foo/schemas.yml  # This will raise an error if it defines 'user' again
other_schema:
  type: object
  properties:
    value:
      type: string

Schemas follow the JSON Schema specification, which provides features like type validation, required properties, pattern matching, enums, nested objects, arrays and more to define your data structures. For more information about JSON Schema, see the official documentation.

Using Schemas in declared tasks

Schemas can be referenced in your Bubblescript code using the @schemas constant, to declare tasks with input and output schemas:

declare task get_price,
  in: @schemas.custom_user,
  out: %{type: "number"},
  description: """
  Gets the price for the user's subscription
  """

See Tasks for more information on declared tasks.

Using Schemas in functions

Schemas can be used to declare runtime-typed functions in your Bubblescript code using the @schemas constant:

function get_user_name(_user :: @schemas.user) :: %{type: "string"} do
  return _user.name
end

See Functions for more information on typed functions.