YAML and RAML - sgml/signature GitHub Wiki

YAML is a text based format allowing programmers to store structured data in a hierarchy. YAML is designed to be human and machine readable with a minimum of overhead. The YAML specification can be found at yaml.org. There is also a reference card

Comments start with # and go till newline, comments must be separated from other tokens by whitespace. Whitespace isn't free, indentation must be spaces, not tabs. YAML will consider that lines prefixed with more spaces than the parent key are contained inside it. Moreover, all lines must be prefixed with the same amount of spaces to belong to the same map.

YAML has sequences and mappings as collection types, both can be represented in flow and block style.

An sequence of scalar strings in YAML looks like:

[ one, two, three ]   # flow style

# or block style

- one
- two
- three

A mapping consists of key/value pairs:

index: 4  # block style
name: nali

# or 

{ index: 4, name: nali }   # flow style

# or nested (equivalent of { level: { one: { two: fun } } }):

level:

  one:

    two: fun

Splitting text strings over multiple lines

- Without quotes:
   You can just
   split a long piece of text like this.
- With quotes:
    "[But be careful:
     if you \"need\" punctuation, put double quotes around it. You can ev\
     en split without spaces by using backslashes."
- Or single quotes:
    'This works
     but isn''t as flexible'
- If you want to keep those new line characters: | 
    Then do
    it this way with 
    a pipe (|) character. (This string has three \n characters)
- Or you can have just the one final new line: >
    This string has
    just one \n character, at the very end.
- Block indicators:
    Look up >-, >+, |- and |+ for fine tuning.

Basic YAML types

integer: 25
string: "25"
float: 25.0
boolean: true
null type: null

Aliases(*) and Anchors(&)

  • Aliases are like XML DTD IDs
  • Anchors are like XML DTD IDRefs
svg:
  width: 200
  height: 200
  xmlns: "http://www.w3.org/2000/svg"
  elements:
    - &circle
      circle:
        id: myCircle
        cx: 50
        cy: 50
        r: 40
        stroke: black
        fill: blue
    - use:
        href: *circle
        x: 100
        fill: red

Escaping

YAML supports three styles of escape notation:

  1. Entity Escapes

    a. space: " "

    b. colon: ":"

    c. ampersand: "&"

  2. Unicode Escapes

    a. space: "\u0020"

    b. single quote: "\u0027"

    c. double quote: "\u0022"

  3. Quoted Escapes

    a. double quote in single quote: 'Is "I always lie" a true statement?'

    b. nested double quote: " She said, "I quit" "

    c. nested single quote: ' He was speechless: '' '

I've been producing and consuming YAML lately. If you have objects serialized to text, you need some form of introspection to reconstruct them with a generic parser. The YAML parser does not know or care about the code in those other modules. It just assumes that the names in the input correspond to classes currently loaded by whomever called the parser. It relies on the language's introspection system to convert the strings in the YAML into calls to constructors.

Rules

https://yamllint.readthedocs.io/en/stable/rules.html

Tools

http://yaml-online-parser.appspot.com/

https://yamllint.com

https://github.com/mikestead/hx-yaml/blob/master/src/yaml/Parser.hx

Queries

+pyyaml "yaml lists" +dump

python yaml recipes activestate

yaml +python +ruby +dump

Scripts

Spellcheck against a dictionary

import yaml

# Function to check if a key contains any of the specified words
def contains_keywords(key, keywords):
    return any(keyword in key for keyword in keywords)

# Load the YAML file
with open('your_file.yaml', 'r') as file:
    data = yaml.safe_load(file)

# Keywords to check for
keywords = ["foo", "bar", "une"]

# Function to recursively check keys in the YAML data
def check_keys(data, keywords):
    if isinstance(data, dict):
        for key, value in data.items():
            if contains_keywords(key, keywords):
                print(f"Key '{key}' contains one of the keywords.")
            check_keys(value, keywords)
    elif isinstance(data, list):
        for item in data:
            check_keys(item, keywords)

# Check the keys in the loaded YAML data
check_keys(data, keywords)

Custom Directives

To call Python code from custom directives in YAML, you can use a combination of YAML for configuration and Python for processing. Here's a high-level approach:

  1. Define the Custom Directive in YAML: Specify the directive and its parameters in YAML.
  2. Process the YAML with Python: Use a Python script to read the YAML file, interpret the custom directives, and execute the corresponding Python code.

Example

Step 1: Define the Custom Directive in YAML

%YAML 1.2
%TAG !mytag! http://example.com/tags/
---
!mytag!execute:
  script: "my_script.py"
  args:
    - "arg1"
    - "arg2"

### Step 2: Process the Directive in Python

Read the YAML file, check for the custom directive, and execute the specified script with the provided arguments.

import yaml

def execute_script(script, args): # Execute the Python script with the provided arguments exec(f"import {script}\n{script}.main(*{args})")

Load the YAML file

with open('config.yaml', 'r') as file: data = yaml.safe_load(file)

Check if the custom directive is present

if 'execute' in data: execute_script(data['execute']['script'], data['execute']['args'])


### !include directive
Use a YAML parser which supports the [`!include` directive](https://pypi.org/project/pyyaml-include/) to use it for transclusion

#### Example

%YAML 1.2

main.yaml

included_foo: !include foo.yaml included_bar: !include bar.yaml

%YAML 1.2

foo.yaml

key1: value1 key2: value2

%YAML 1.2

bar.yaml

key3: value3 key4: value4


## References

https://www.rfc-editor.org/rfc/rfc9512.html

https://www.yaml.info/learn/document.html#directive

https://ref.coddy.tech/yaml/yaml-directives
https://docs.stacktape.com/configuration/directives/

https://metacpan.org/pod/Text::FrontMatter::YAML

https://pypi.org/project/python-frontmatter/

https://www.earthdata.nasa.gov/s3fs-public/imported/YAML%201.2%20Spec.pdf

https://builtin.com/software-engineering-perspectives/yaml-vs-json

https://www.snaplogic.com/blog/json-vs-yaml-whats-the-difference-and-which-one-is-right-for-your-enterprise

https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html

https://gist.github.com/oconnor663/9aeb4ed56394cb013a20

http://sweetohm.net/article/introduction-yaml.en.html

https://rtfm.co.ua/en/what-is-yaml-its-overview-basic-data-types-yaml-vs-json-and-pyyaml/

http://www.chrisrolle.com/en/blog/yaml-list

https://confit.readthedocs.io/en/latest/

https://itnext.io/what-is-yaml-its-overview-basic-data-types-yaml-vs-json-and-pyyaml-92059d1a24fa

https://www.redhat.com/sysadmin/yaml-tips

https://rollout.io/blog/yaml-tutorial-everything-you-need-get-started/

https://hackersandslackers.com/simplify-your-python-projects-configuration/

https://www.serendipidata.com/posts/safe-api-design-and-pyyaml

https://yaml.readthedocs.io/en/latest/api.html

http://docs.racket-lang.org/yaml/

https://news.ycombinator.com/item?id=17358103

https://www.infoq.com/articles/tosca-docker-orchestration/

https://garywoodfine.com/serverless-aws-lambda-dependency-injection/


## RAML

* https://www.sitepoint.com/raml-restful-api-modeling-language/

* https://www.genuitec.com/understanding-raml/

* https://web.archive.org/web/20141126115053/http://blogs.mulesoft.org/designing-restful-api-longevity/

* https://raml.org

* https://www.github.com/topics/raml

Games

⚠️ **GitHub.com Fallback** ⚠️