Apache Brooklyn YAML Style Guide

brooklyn-style.md

Apache Brooklyn YAML Style Guide

Statements should be interpreted according to RFC 2119.

Normative Statements

1. Blueprints MUST place all configuration inside a brooklyn.config map, and MUST use the fully qualified configuration key name
2. Lists MUST be indented properly, to allow IDE folding to work properly
3. Keywords MUST be formatted as lowerCamel tokens
4. Sensor, configuration key and section names MUST be formatted as lower-hyphen.dot-separated tokens
5. The preamble for a catalog entry SHOULD contain the following keys, which MUST appear in this order:
   • version
   • id
   • name
   • description
   • iconUrl
   • origin
   • license
   • licenseUrl
   • publish
   • libraries (or brooklyn.libraries)
   • includes
6. Entities SHOULD contain the following sections, which MUST appear in this order:
   • brooklyn.parameters
   • brooklyn.config
   • brooklyn.initializers
   • brooklyn.enrichers
   • brooklyn.policies
   • brooklyn.children
7. Catalog items SHOULD contain the following keys, which MUST appear in this order:
   • id
   • name
   • description
   • itemType
   • item
8. Entities and entity specifications SHOULD contain the following keys, which MUST appear in this order:
   • type
   • id
   • name
   • description
   • services
9. Names MUST be quoted strings
10. The description value MUST use the multi-line string syntax
11. Parameters SHOULD use the following keys, which MUST appear in this order:
    • name
    • label
    • description
    • type
    • default
    • constraints

Informative Resources

The following YAML fragments show how these rules are to be interpreted. Note that in general only a single child of each type appears in the sections supporting a list of items.

Blueprint

id: entity-id
name: "Name"
description: |
  Example YAML file.
  Description
services:
  - type: brooklyn-type
    id: service-id
    name: "Service"
    brooklyn.parameters:
      - name: param.name
        label: "Param Name"
        type: duration
        default: 1d
        constraints:
          - required: true
    brooklyn.config:
      config.key: "value"
    brooklyn.initializers:
      - type: org.example.Initializer
    brooklyn.enrichers:
      - type: org.example.Enricher
        brooklyn.config:
          enricher.config: "value"
    brooklyn.policies:
      - type: org.example.Policy
        brooklyn.config:
          policy.config: "value"
    brooklyn.children:
      - type: brooklyn-type
        id: entity-id
        name: "Entity"
        brooklyn.config:
          entity.config: "value"
      - type: brooklyn-type
        id: other-id
        name: "Other"
        brooklyn.config:
          other.config: "value"

Catalog Entry

brooklyn.catalog:
  version: "1.2.3-SNAPSHOT"
  id: catalog-id
  name: "Catalog Entry"
  description: |
    Catalog entry descriptive text
  iconUrl: https://example.org/logo.png
  origin: https://github.com/example/example/
  license: LICENSE-1.0
  licenseUrl: https://example.org/license.txt
  publish:
    description: |
      Catalog entry published description
    license_code: LICENSE-1.0
    license_url: https://example.org/license.txt
    overview: README.md
    qa:
      - tests/tests.bom
      - tests/integration.bom
  libraries:
    - https://example.org/repository/code-1.2.3.jar
    - https://example.org/repository/file-1.2.3.jar
  includes:
    - https://example.org/shared.bom
    - https://example.org/other.bom

Note the incosistency in keyword formatting under the publish section; this is required for compatibility with the community catalog project.