├── LICENSE.md ├── MORE ├── README.md ├── article.md ├── bool.md └── null.md ├── NOTES.md └── README.md /LICENSE.md: -------------------------------------------------------------------------------- 1 | CC0 1.0 Universal 2 | 3 | Statement of Purpose 4 | 5 | The laws of most jurisdictions throughout the world automatically confer 6 | exclusive Copyright and Related Rights (defined below) upon the creator and 7 | subsequent owner(s) (each and all, an "owner") of an original work of 8 | authorship and/or a database (each, a "Work"). 9 | 10 | Certain owners wish to permanently relinquish those rights to a Work for the 11 | purpose of contributing to a commons of creative, cultural and scientific 12 | works ("Commons") that the public can reliably and without fear of later 13 | claims of infringement build upon, modify, incorporate in other works, reuse 14 | and redistribute as freely as possible in any form whatsoever and for any 15 | purposes, including without limitation commercial purposes. These owners may 16 | contribute to the Commons to promote the ideal of a free culture and the 17 | further production of creative, cultural and scientific works, or to gain 18 | reputation or greater distribution for their Work in part through the use and 19 | efforts of others. 20 | 21 | For these and/or other purposes and motivations, and without any expectation 22 | of additional consideration or compensation, the person associating CC0 with a 23 | Work (the "Affirmer"), to the extent that he or she is an owner of Copyright 24 | and Related Rights in the Work, voluntarily elects to apply CC0 to the Work 25 | and publicly distribute the Work under its terms, with knowledge of his or her 26 | Copyright and Related Rights in the Work and the meaning and intended legal 27 | effect of CC0 on those rights. 28 | 29 | 1. Copyright and Related Rights. A Work made available under CC0 may be 30 | protected by copyright and related or neighboring rights ("Copyright and 31 | Related Rights"). Copyright and Related Rights include, but are not limited 32 | to, the following: 33 | 34 | i. the right to reproduce, adapt, distribute, perform, display, communicate, 35 | and translate a Work; 36 | 37 | ii. moral rights retained by the original author(s) and/or performer(s); 38 | 39 | iii. publicity and privacy rights pertaining to a person's image or likeness 40 | depicted in a Work; 41 | 42 | iv. rights protecting against unfair competition in regards to a Work, 43 | subject to the limitations in paragraph 4(a), below; 44 | 45 | v. rights protecting the extraction, dissemination, use and reuse of data in 46 | a Work; 47 | 48 | vi. database rights (such as those arising under Directive 96/9/EC of the 49 | European Parliament and of the Council of 11 March 1996 on the legal 50 | protection of databases, and under any national implementation thereof, 51 | including any amended or successor version of such directive); and 52 | 53 | vii. other similar, equivalent or corresponding rights throughout the world 54 | based on applicable law or treaty, and any national implementations thereof. 55 | 56 | 2. Waiver. To the greatest extent permitted by, but not in contravention of, 57 | applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and 58 | unconditionally waives, abandons, and surrenders all of Affirmer's Copyright 59 | and Related Rights and associated claims and causes of action, whether now 60 | known or unknown (including existing as well as future claims and causes of 61 | action), in the Work (i) in all territories worldwide, (ii) for the maximum 62 | duration provided by applicable law or treaty (including future time 63 | extensions), (iii) in any current or future medium and for any number of 64 | copies, and (iv) for any purpose whatsoever, including without limitation 65 | commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes 66 | the Waiver for the benefit of each member of the public at large and to the 67 | detriment of Affirmer's heirs and successors, fully intending that such Waiver 68 | shall not be subject to revocation, rescission, cancellation, termination, or 69 | any other legal or equitable action to disrupt the quiet enjoyment of the Work 70 | by the public as contemplated by Affirmer's express Statement of Purpose. 71 | 72 | 3. Public License Fallback. Should any part of the Waiver for any reason be 73 | judged legally invalid or ineffective under applicable law, then the Waiver 74 | shall be preserved to the maximum extent permitted taking into account 75 | Affirmer's express Statement of Purpose. In addition, to the extent the Waiver 76 | is so judged Affirmer hereby grants to each affected person a royalty-free, 77 | non transferable, non sublicensable, non exclusive, irrevocable and 78 | unconditional license to exercise Affirmer's Copyright and Related Rights in 79 | the Work (i) in all territories worldwide, (ii) for the maximum duration 80 | provided by applicable law or treaty (including future time extensions), (iii) 81 | in any current or future medium and for any number of copies, and (iv) for any 82 | purpose whatsoever, including without limitation commercial, advertising or 83 | promotional purposes (the "License"). The License shall be deemed effective as 84 | of the date CC0 was applied by Affirmer to the Work. Should any part of the 85 | License for any reason be judged legally invalid or ineffective under 86 | applicable law, such partial invalidity or ineffectiveness shall not 87 | invalidate the remainder of the License, and in such case Affirmer hereby 88 | affirms that he or she will not (i) exercise any of his or her remaining 89 | Copyright and Related Rights in the Work or (ii) assert any associated claims 90 | and causes of action with respect to the Work, in either case contrary to 91 | Affirmer's express Statement of Purpose. 92 | 93 | 4. Limitations and Disclaimers. 94 | 95 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 96 | surrendered, licensed or otherwise affected by this document. 97 | 98 | b. Affirmer offers the Work as-is and makes no representations or warranties 99 | of any kind concerning the Work, express, implied, statutory or otherwise, 100 | including without limitation warranties of title, merchantability, fitness 101 | for a particular purpose, non infringement, or the absence of latent or 102 | other defects, accuracy, or the present or absence of errors, whether or not 103 | discoverable, all to the greatest extent permissible under applicable law. 104 | 105 | c. Affirmer disclaims responsibility for clearing rights of other persons 106 | that may apply to the Work or any use thereof, including without limitation 107 | any person's Copyright and Related Rights in the Work. Further, Affirmer 108 | disclaims responsibility for obtaining any necessary consents, permissions 109 | or other rights required for any use of the Work. 110 | 111 | d. Affirmer understands and acknowledges that Creative Commons is not a 112 | party to this document and has no duty or obligation with respect to this 113 | CC0 or use of the Work. 114 | 115 | For more information, please see 116 | 117 | -------------------------------------------------------------------------------- /MORE/README.md: -------------------------------------------------------------------------------- 1 | 2 | # Structured (Meta) Data in Text Formats 3 | 4 | 5 | **YAML (Ain't Markup Language) Family** 6 | 7 | - "Standard" YAML 8 | - "Safe" YAML 9 | 10 | 11 | **TOML (Tom's Obvious, Minimal Language) & INI Family** 12 | 13 | - TOML 14 | - INI -- All Values Strings?? 15 | 16 | 17 | **JSON (JavaScript Object Notation) Family** 18 | 19 | - "Plain" JSON 20 | - JSON5 21 | - SON 22 | - HJSON 23 | - ... 24 | 25 | 26 | **CSV (Comma-Separated Values) Family** 27 | 28 | - "Plain" CSV -- All Values Strings?? 29 | 30 | 31 | **Others** 32 | 33 | - Properties -- All Values Strings?? 34 | 35 | 36 | 37 | 38 | 39 | {% include_relative article.md %} 40 | 41 | 42 | 43 | 44 | 45 | **Data Types** 46 | 47 | Primitive / Simple 48 | 49 | - String 50 | - Numbers 51 | - Bool(ean) 52 | - Null / Nil 53 | - Date / Datetime / Timestamp 54 | - Character ??? 55 | 56 | Composite 57 | 58 | - Hash (Table) / Object / Collection 59 | - Array / List 60 | 61 | 62 | {% include_relative bool.md %} 63 | 64 | {% include_relative null.md %} 65 | -------------------------------------------------------------------------------- /MORE/article.md: -------------------------------------------------------------------------------- 1 | 2 | ## Article Meta Data (Front Matter) Sample 3 | 4 | 5 | 6 | ### TOML (Tom's Obvious, Minimal Language) 7 | 8 | Note: Use `+++`to begin and end meta data (front matter) block. 9 | 10 | 11 | ``` toml 12 | +++ 13 | date = "2016-12-14T21:27:05.454Z" 14 | publishdate = "2016-12-14T21:27:05.454Z" 15 | 16 | title = "Deep dive into TOML, JSON and YAML" 17 | tags = ["toml","yaml","json", "front matter"] 18 | 19 | type = "article" 20 | 21 | [amp] 22 | elements = [] 23 | 24 | [article] 25 | lead = "Lorem ipsum." 26 | category = "frontmatter" 27 | related = [] 28 | 29 | [sitemap] 30 | changefreq = "monthly" 31 | priority = 0.5 32 | filename = "sitemap.xml" 33 | +++ 34 | ``` 35 | 36 | 37 | ### YAML (Ain't Markup Language) 38 | 39 | Note: Use `---` to begin and end meta data (front matter) block. 40 | 41 | ``` yaml 42 | --- 43 | date: '2016-12-14T21:27:05.454Z' 44 | publishdate: '2016-12-14T21:27:05.454Z' 45 | title: Deep dive into TOML, JSON and YAML 46 | tags: 47 | - toml 48 | - yaml 49 | - json 50 | - front matter 51 | type: article 52 | amp: 53 | elements: [] 54 | article: 55 | lead: Lorem ipsum. 56 | category: frontmatter 57 | related: [] 58 | sitemap: 59 | changefreq: monthly 60 | priority: 0.5 61 | filename: sitemap.xml 62 | --- 63 | ``` 64 | 65 | ### JSON (JavaScript Object Notation) 66 | 67 | Note: Use `{ }` or `[ ]` to begin and end meta data (front matter) block. 68 | 69 | ``` json 70 | { 71 | "date" : "2016-12-14T21:27:05.454Z", 72 | "publishdate" : "2016-12-14T21:27:05.454Z", 73 | "title" : "Deep dive into TOML, JSON and YAML", 74 | "tags" : ["toml","yaml","json", "front matter"], 75 | "type" : "article", 76 | "amp" : { 77 | "elements" : [] 78 | }, 79 | "article" : { 80 | "lead" : "Lorem ipsum.", 81 | "category" : "frontmatter", 82 | "related" : [] 83 | }, 84 | "sitemap" : { 85 | "changefreq" : "monthly", 86 | "priority" : 0.5, 87 | "filename" : "sitemap.xml" 88 | } 89 | } 90 | ``` 91 | 92 | ### JSON5 (JavaScript Object Notation) 93 | 94 | Note: Use `{ }` or `[ ]` to begin and end meta data (front matter) block. 95 | 96 | ``` json5 97 | { 98 | date : "2016-12-14T21:27:05.454Z", 99 | publishdate : "2016-12-14T21:27:05.454Z", 100 | title : "Deep dive into TOML, JSON and YAML", 101 | tags : ["toml","yaml","json", "front matter"], 102 | type : "article", 103 | amp : { 104 | elements : [] 105 | }, 106 | article : { 107 | lead : "Lorem ipsum.", 108 | category : "frontmatter", 109 | related : [] 110 | }, 111 | sitemap : { 112 | changefreq : "monthly", 113 | priority : 0.5, 114 | filename : "sitemap.xml" 115 | } 116 | } 117 | ``` 118 | 119 | -------------------------------------------------------------------------------- /MORE/bool.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Bool(ean) 4 | 5 | 6 | ### TOML 7 | 8 | ``` toml 9 | bool1 = true 10 | bool2 = false 11 | ``` 12 | 13 | ### YAML 14 | 15 | ``` yaml 16 | bool1: true 17 | bool2: false 18 | ``` 19 | 20 | todo: add yes|no and on|off - others too (0|1 ??)? 21 | 22 | 23 | ### JSON 24 | 25 | ``` json 26 | { 27 | "bool1": true, 28 | "bool2": false 29 | } 30 | ``` 31 | 32 | -------------------------------------------------------------------------------- /MORE/null.md: -------------------------------------------------------------------------------- 1 | 2 | ## Null / Nil 3 | 4 | 5 | ### TOML 6 | 7 | - not possible? 8 | 9 | 10 | 11 | ### YAML 12 | 13 | ``` yaml 14 | null1: null 15 | null2: ~ 16 | ``` 17 | 18 | ### JSON 19 | 20 | ``` json 21 | { 22 | "null1": null 23 | } 24 | ``` 25 | 26 | -------------------------------------------------------------------------------- /NOTES.md: -------------------------------------------------------------------------------- 1 | # Notes 2 | 3 | 4 | ## More YAML Resources 5 | 6 | 7 | - [Awesome YAML (@dreftymac)](https://github.com/dreftymac/awesome-yaml) 8 | 9 | 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | ``` yaml 3 | The design goals for YAML: 4 | 5 | - YAML is easily readable by humans. 6 | - YAML data is portable between programming languages. 7 | - YAML matches the native data structures of agile languages. 8 | - YAML has a consistent model to support generic tools. 9 | - YAML supports one-pass processing. 10 | - YAML is expressive and extensible. 11 | - YAML is easy to implement and use. 12 | ``` 13 | 14 | 15 | # Awesome YAML (Ain't Markup Language) 16 | 17 | A collection of Awesome YAML (Ain't Markup Language) goodies for structured (meta) data in text. 18 | 19 | 20 | #### _Contributions welcome. Anything missing? Send in a pull request. Thanks._ 21 | 22 | 23 | ## Formats 24 | 25 | ### "Standard" YAML 26 | 27 | **YAML HQ** 28 | 29 | - [`yaml.org`](http://www.yaml.org) - official YAML website by Clark C. Evans 30 | - [YAML Spec v1.2](http://yaml.org/spec/1.2/spec.html) - 3rd edition, Oct 2009 31 | - [YAML Quick Reference Card](http://www.yaml.org/refcard.html) - one-page cheat sheet 32 | 33 | ### "Safe" YAML, "Strict" YAML 34 | 35 | - [`strictyaml`](https://github.com/crdoconnor/strictyaml) - a type-safe YAML parser that parses and validates a restricted subset of the YAML specification 36 | - [YAML Features Removed](https://hitchdev.com/strictyaml/features-removed/) 37 | - NO Implicit Typing 38 | - NO Direct representations of objects 39 | - NO Duplicate Keys Disallowed 40 | - NO Explicit tags 41 | - NO Node anchors and refs 42 | - NO Flow style 43 | 44 | 45 | ### Nested Text - YAML Simplified, YAML Evolved 46 | 47 | _"Safer" YAML - YAML Redux_ 48 | 49 | - [`nestedtext.org`](https://nestedtext.org), [(github)](https://github.com/KenKundert/nestedtext) - a human friendly data format similar to YAML but without the complexity and risk of YAML 50 | 51 | Example: 52 | 53 | ``` 54 | # Contact information for our officers 55 | 56 | president: 57 | name: Katheryn McDaniel 58 | address: 59 | > 138 Almond Street 60 | > Topeka, Kansas 20697 61 | phone: 62 | cell: 1-210-555-5297 63 | home: 1-210-555-8470 64 | # Katheryn prefers that we always call her on her cell phone. 65 | email: KateMcD@aol.com 66 | additional roles: 67 | - board member 68 | ``` 69 | 70 | 71 | ## Articles 72 | 73 | - [**YAML Quick Reference (Cheat Sheet) for Jekyll Data Files, Front Matter and Collections**](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md), Planet Jekyll 74 | - [**Learn YAML in Y Minutes**](https://learnxinyminutes.com/docs/yaml), Learn X in Y minutes series, 75 | - [**Deep dive into TOML, JSON and YAML**](https://gohugohq.com/howto/toml-json-yaml-comparison/), Go Hugo HQ, Dec 2016 76 | - [**YAML @ Wikipedia**](https://en.wikipedia.org/wiki/YAML) 77 | 78 | 79 | ## Tips & Gotchas 80 | 81 | 82 | **Strings with Colons (`:`)** 83 | 84 | When to use quotes for your strings? 85 | 86 | If your string includes a colon (`:`) followed by a space you MUST quote your string. Otherwise, the colon is interpreted as a key/value separator (e.g. _key: value_). Example: 87 | 88 | ``` yaml 89 | title: "Text Processing with Ruby: Extract Value from the Data That Surrounds You" 90 | title: "Sinatra: Up and Running - Ruby for the Web, Simply" 91 | title: "Using JRuby: Bringing Ruby to Java" 92 | ``` 93 | 94 | Note: You can quote your strings using double quotes (`""`) e.g. "Using JRuby: Bringing Ruby to Java" 95 | or single quotes(`''`) e.g. 'Using JRuby: Bringing Ruby to Java'. 96 | 97 | 98 | 99 | **No Tabs (\t) for Indentation - Use Spaces, Period** 100 | 101 | Note: Always use spaces for indentation, period. 102 | Make sure no tabs (`\t`) have somehow ended up in your datafile leading to 103 | unexpected results. 104 | 105 | 106 | 107 | **Predefined Boolean 'n' No Value Constants - True/False, Yes/No, On/Off, ~/Null** 108 | 109 | Note: The boolean `true` and `false` constants e.g.: 110 | 111 | ``` 112 | true, True, TRUE 113 | y, Y, yes, YES, YES 114 | on, ON, ON 115 | false, False, FALSE 116 | n, N, no, No, NO 117 | off, Off, OFF 118 | ``` 119 | 120 | will become boolean values e.g. `true` or `false`. If you want end-up with a string e.g.: 121 | 122 | ``` yaml 123 | recommend: Yes # note: will become => true (boolean) 124 | ``` 125 | 126 | make sure you use a quoted version e.g.: 127 | 128 | ``` yaml 129 | recommend: "Yes" # note: will become => "Yes" (string) 130 | ``` 131 | 132 | 133 | Note: The same holds for the no value null constants e.g.: 134 | 135 | ``` yaml 136 | ~ 137 | null, Null, NULL 138 | ``` 139 | 140 | will become => `null` (no value). Note: A key without a value will end-up with a `null` value (and not an empty string, for example). To get an empty string use `""` e.g.: 141 | 142 | ``` yaml 143 | key1: # note: value will become => null (no value); same as key1: null or key1: ~ 144 | key2: "" # note: value will become => "" (string) 145 | ``` 146 | 147 | 148 | 149 | ## JSON 150 | 151 | _JSON is (a subset of) YAML, that is YAML is JSON but JSON is NOT YAML ;-)_ 152 | 153 | Example: Use the inline style for lists (that is, JSON arrays) 154 | and hashes (that is, JSON objects) for an alternative "JSON-style" syntax: 155 | 156 | 157 | ``` json 158 | [ 159 | { "title": "football.db - Open Football Data", 160 | "url": "https://github.com/openfootball" 161 | }, 162 | { "title": "beer.db - Open Beer, Brewery 'n' Brewpub Data", 163 | "url": "https://github.com/openbeer" 164 | } 165 | ] 166 | ``` 167 | 168 | is the same as: 169 | 170 | ``` yaml 171 | - title : football.db - Open Football Data 172 | url : https://github.com/openfootball 173 | - title : beer.db - Open Beer, Brewery 'n' Brewpub Data 174 | url : https://github.com/openbeer 175 | ``` 176 | 177 | 178 | 179 | 180 | ## Tools & Services 181 | 182 | - [**YAML Linter @ yamllint.com**](http://www.yamllint.com) - online YAML validator / checker 183 | - [**YAML Validator @ Code Beautify**](https://codebeautify.org/yaml-validator) - online YAML validator / checker 184 | - [**YAML Comparator @ yamline**](https://yamline.com/compare/) - online YAML comparator 185 | - [**Yamlinc**](https://github.com/javanile/yamlinc) - compose multiple files using $include tag / compiler 186 | - [**dasel ("data-selector")**](https://github.com/tomwright/dasel) - Query and update data structures using selectors from the command line. Comparable to [jq](https://github.com/stedlan/jq) / [yq](https://github.com/kislyuk/yq) but supports JSON, YAML, TOML and XML with zero runtime dependencies. 187 | 188 | 189 | ## No Body Wants To Write YAML 190 | 191 | ``` yaml 192 | No: 193 | Body: 194 | Wants: 195 | To: 196 | Write: 197 | - YAML 198 | ``` 199 | 200 | - [**`noyaml.com`**](https://noyaml.com), [(github)](https://github.com/ghuntley/noyaml) - a rant about the state of devops tooling / the infrastructure sector 201 | 202 | Mandatory "No Body Wants To Write YAML" reading list: 203 | - [Today we’re going to look at some general problems with the YAML format](https://arp242.net/yaml-config.html) 204 | - [We replaced 1,000 lines of YAML with 10 structs and people started contributing again](https://tinyurl.com/lessons-in-over-engineering) 205 | - [What if you used the same language and tools you use to define your app to define your infrastructure?](https://twitter.com/ellism/status/1008728148131733504) 206 | - [A YAML file is almost always still 'valid' even if it is trunca](https://twitter.com/colmmacc/status/1057316977457324032) 207 | - [The bug was that the YAML parser ignored the negative signs ... so negative GPS coordinates became positive ones](https://twitter.com/colmmacc/status/1063470541464461312) 208 | - [Every YAML parser is a custom YAML parser](https://matrix.yaml.io/valid.html) 209 | - [There are 63 different ways to write multi-line strings in YAML](https://stackoverflow.com/a/21699210/1094085) 210 | 211 | 212 | 213 | ## Misc 214 | 215 | - [**Feed.TXT**](https://feedtxt.github.io) - web feed format with meta data in YAML 216 | - [**YAML @ Stackoverflow**](https://stackoverflow.com/tags/yaml/info) - frequently asked questions (and answers) about YAML 217 | - [**Manifest**](https://manifest.build) - a complete backend in 1 YAML file 218 | 219 | 220 | ## Meta 221 | 222 | **License** 223 | 224 | ![](https://publicdomainworks.github.io/buttons/zero88x31.png) 225 | 226 | The awesome list is dedicated to the public domain. Use it as you please with no restrictions whatsoever. 227 | 228 | **Questions? Comments?** 229 | 230 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 231 | --------------------------------------------------------------------------------