Skip to content

v1.88.0
Compare
Choose a tag to compare
@cloudposse-releaser cloudposse-releaser released this 02 Sep 17:33
· 41 commits to refs/heads/main since this release
v1.88.0
b52762e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Update the `Go` YAML lib from `gopkg.in/yaml.v2` to `gopkg.in/yaml.v3`. Support YAML v1.2 (latest version) @aknysh (#690) ## what
  • Update the Go YAML lib from gopkg.in/yaml.v2 to gopkg.in/yaml.v3
  • Support YAML v1.2 (latest version)
  • Support YAML explicit typing (explicit typing is denoted with a tag using the exclamation point (“!”) symbol)
  • Improve code, e.g. add YAML wrappers in one yaml_utils file (which imports gopkg.in/yaml.v3) to control all YAML marshaling and un-marshaling from one place

why

gopkg.in/yaml.v3

The main differences between gopkg.in/yaml.v3 and gopkg.in/yaml.v2 include enhancements in functionality, bug fixes, and improvements in performance. Here's a summary of key distinctions:

1. Better Conformance to YAML 1.2 Specification:

  • gopkg.in/yaml.v3 offers improved support for the YAML 1.2 specification. This includes better handling of complex YAML features such as core schema, block styles, and anchors.
  • gopkg.in/yaml.v2 is more aligned with YAML 1.1, meaning it might not fully support some of the YAML 1.2 features.

2. Node API Changes:

  • gopkg.in/yaml.v3 introduced a new Node API, which provides more control and flexibility over parsing and encoding YAML documents. This API is more comprehensive and allows for detailed inspection and manipulation of YAML content.
  • gopkg.in/yaml.v2 has a simpler node structure and API, which might be easier to use for simple use cases but less powerful for advanced needs.

3. Error Handling:

  • gopkg.in/yaml.v3 offers improved error messages and better context for where an error occurs during parsing. This makes it easier to debug and correct YAML syntax errors.
  • gopkg.in/yaml.v2 has less detailed error reporting, which can make debugging more challenging.

4. Support for Line and Column Numbers:

  • gopkg.in/yaml.v3 includes support for tracking line and column numbers of nodes, which can be useful when dealing with large or complex YAML files.
  • gopkg.in/yaml.v2 does not provide this level of detail in terms of tracking where nodes are located within the YAML document.

5. Performance:

  • gopkg.in/yaml.v3 has various performance improvements, particularly in the encoding and decoding process. However, these improvements might not be significant in all scenarios.
  • gopkg.in/yaml.v2 might be slightly faster in certain cases, particularly when dealing with very simple YAML documents, due to its simpler feature set.

6. Deprecation of Legacy Functions:

  • gopkg.in/yaml.v3 deprecates some older functions that were available in v2, encouraging developers to use more modern and efficient alternatives.
  • gopkg.in/yaml.v2 retains these older functions, which may be preferred for backward compatibility in some projects.

7. Anchors and Aliases:

  • gopkg.in/yaml.v3 has better handling of YAML anchors and aliases, making it more robust in scenarios where these features are heavily used.
  • gopkg.in/yaml.v2 supports anchors and aliases but with less robustness and flexibility.

8. API Changes and Compatibility:

  • gopkg.in/yaml.v3 introduces some API changes that are not backward-compatible with v2. This means that upgrading from v2 to v3 might require some code changes.
  • gopkg.in/yaml.v2 has been widely used and is stable, so it may be preferable for projects where stability and long-term support are critical.

YAML v1.2

YAML v1.1 and YAML v1.2 differ in several key aspects, particularly in terms of specification, syntax, and data type handling. Here's a breakdown of the most significant differences:

1. Specification and Goals:

  • YAML 1.1 was designed with some flexibility in its interpretation of certain constructs, aiming to be a human-readable data serialization format that could also be easily understood by machines.
  • YAML 1.2 was aligned more closely with the JSON specification, aiming for better interoperability with JSON and standardization. YAML 1.2 is effectively a superset of JSON.

2. Boolean Values:

  • YAML 1.1 has a wide range of boolean literals, including y, n, yes, no, on, off, true, and false. This flexibility could sometimes lead to unexpected interpretations.
  • YAML 1.2 standardizes boolean values to true and false, aligning with JSON. This reduces ambiguity and ensures consistency.

3. Integers with Leading Zeros:

  • YAML 1.1 interprets integers with leading zeros as octal (base-8) numbers. For example, 012 would be interpreted as 10 in decimal.
  • YAML 1.2 no longer interprets numbers with leading zeros as octal. Instead, they are treated as standard decimal numbers, which aligns with JSON. This change helps avoid confusion.

4. Null Values:

  • YAML 1.1 allows a variety of null values, including null, ~, and empty values (e.g., an empty string).
  • YAML 1.2 standardizes the null value to null (or an empty value), aligning with JSON's null representation.

5. Tag Handling:

  • YAML 1.1 uses an unquoted !! syntax for tags (e.g., !!str for a string). The tag system is more complex and includes non-standard tags that can be confusing.
  • YAML 1.2 simplifies tag handling and uses a more JSON-compatible syntax, with less emphasis on non-standard tags. Tags are optional and less intrusive in most use cases.

6. Floating-Point Numbers:

  • YAML 1.1 supports special floating-point values like .inf, -.inf, and .nan with a dot notation.
  • YAML 1.2 aligns with JSON and supports Infinity, -Infinity, and NaN, which are the standard representations in JSON.

7. Direct JSON Compatibility:

  • YAML 1.2 is designed to be a strict superset of JSON, meaning any valid JSON document is also a valid YAML 1.2 document. This was not the case in YAML 1.1, where certain JSON documents could be interpreted differently.

8. Indentation and Line Breaks:

  • YAML 1.2 introduced more consistent handling of line breaks and indentation. While YAML 1.1 was flexible, it sometimes led to ambiguities in how line breaks and whitespace were interpreted.
  • YAML 1.2 has clearer rules, reducing the potential for misinterpretation of line breaks and indentation.

9. Miscellaneous Syntax Changes:

  • YAML 1.2 introduced some syntax changes for better clarity and alignment with JSON. For instance, YAML 1.2 removed support for single-quoted multiline strings, which were present in YAML 1.1.

10. Core Schema vs. JSON Schema:

  • YAML 1.2 introduced the concept of schemas, particularly the Core schema, which aims to be YAML's native schema, and the JSON schema, which strictly follows JSON's data types and structures.
  • YAML 1.1 did not have this formal schema distinction, leading to more flexible but sometimes less predictable data handling.

Summary:

  • YAML 1.2 is more standardized, consistent, and aligned with JSON, making it more predictable and easier to interoperate with JSON-based systems.
  • YAML 1.1 offers more flexibility and a wider range of literal values, but this flexibility can sometimes lead to ambiguities and unexpected behavior.

references

Contributors

aknysh
Assets 17
Loading