Yaml

Overview

YAML (YAML Ain't Markup Language) is a human-readable data serialization language commonly used for configuration files and data exchange between languages. In the context of AllSpice Actions, similar to GitHub Actions, YAML files are used to define workflows that automate software development processes such as building, testing, and deploying applications.

Syntax and Structure

YAML is case-sensitive and uses indentation (spaces, not tabs) to denote structure. Here are key elements of YAML syntax:

• Scalars: Basic, singular values such as strings, numbers, and Booleans.

• Lists: Sequences of items under a single key, denoted by dashes.

• Dictionaries: Sets of key-value pairs, used to map associative data.

• Anchors and Aliases: Useful for duplicating content in a document without repeating it.

YAML Cheatsheet

# Example YAML File Demonstrating Scalars, Lists, Dictionaries, Anchors, and Aliases

# Scalars: Simple key-value pairs (strings, numbers, booleans)
version: "1.0"  # String scalar
debug_mode: true  # Boolean scalar
max_users: 100  # Integer scalar

# List: A sequence of elements
supported_languages:
  - English
  - French
  - Spanish

# Dictionaries: Key-value pairs where values can be complex and nested
database_config:
  host: "localhost"
  port: 5432
  credentials:
    username: "admin"
    password: "secret"

# Anchors and Aliases: Define a node and reuse it elsewhere with an alias
defaults: &default_settings  # This is an anchor
  retry: 3
  timeout: 120
  enable: true

servers:
  - server1:
      <<: *default_settings  # This merges the values defined in the 'default_settings' anchor
      ip: "192.168.1.1"
  - server2:
      <<: *default_settings  # Reuse of the anchor for another server
      ip: "192.168.1.2"

# Using aliases to simplify repeated data
allowed_ips: &ips  # Anchor defining a list
  - "192.168.1.1"
  - "192.168.1.2"

firewall_rules:
  rule1:
    description: "Allow incoming traffic"
    from_ips: *ips  # Alias referencing the 'allowed_ips' list

# Documenting complex structures using nested dictionaries and lists
services:
  web_service:
    description: "Frontend web server"
    protocols:
      - http
      - https
    ports:
      - 80
      - 443

Example PCBA YAML

This example shows a YAML file describing a circuit. This may be useful to understand how YAML is flexible and extensible.

# Electrical Design Configuration YAML File
circuit_id: "Circuit 101"
description: "Basic power distribution circuit for residential lighting."

# Power Sources
power_sources:
  - type: "AC Mains"
    voltage: "120V"
    frequency: "60Hz"

# Components in the circuit
components:
  - resistor:
      id: "R1"
      resistance: "50 ohms"
      power_rating: "10 watts"
  - capacitor:
      id: "C1"
      capacitance: "100uF"
      voltage_rating: "50V"
  - led:
      id: "LED1"
      color: "White"
      forward_voltage: "3.2V"
      current: "20mA"

# Connections specify how components are connected
connections:
  - from: "AC Mains"
    to: "R1"
  - from: "R1"
    to: "LED1"
  - from: "LED1"
    to: "Ground"

# Safety features
safety:
  fuse:
    rating: "5A"
    placement: "before R1"

# Specifications for wiring
wiring:
  - type: "Copper"
    gauge: "18 AWG"
    insulation: "PVC"
    color_code:
      - "Black"  # Hot
      - "White"  # Neutral
      - "Green"  # Ground

# Control Systems (if applicable)
controls:
  switch:
    type: "Toggle"
    location: "Entrance"

# Additional notes
notes:
  - "Ensure all connections are insulated to prevent accidental contact."
  - "Verify grounding according to local electrical codes."

Tips for Writing Effective YAML

• Consistent Indentation: Use the same number of spaces for each level of indentation.

• Quoting Strings: Generally, strings do not require quotes unless they include special characters or start with characters that could be confused with YAML syntax.

• Use Comments: Start comments with # to add useful annotations and explanations.

• Keep It Dry: Utilize anchors and aliases to avoid repetition and keep your YAML files maintainable.

• Validation: Use online YAML validators to check the syntax of your files.