Swiftpack.co - Package - jpsim/Yams



A sweet and swifty YAML parser built on LibYAML.

SwiftPM xcodebuild pod lib lint Nightly codecov


Building Yams requires Xcode 10.x or a Swift 4.1+/5.x toolchain with the Swift Package Manager or CMake and Ninja.


CMake 3.15.1 or newer is required.

cmake -H /path/to/build -G Ninja -S /path/to/yams -DCMAKE_BUILD_TYPE=Release -DFoundation_DIR=/path/to/foundation/build/cmake/modules
cmake --build /path/to/build

To build for macOS, iOS, tvOS, watchOS, additional flags specifying the SDK need to be passed to the compiler. You can do that by adding the -DCMAKE_Swift_FLAGS="-sdk $(xcrun --sdk macosx --show-sdk-path)" to the CMake invocation when configuring.

Swift Package Manager

Add .package(url: "https://github.com/jpsim/Yams.git", from: "2.0.0") to your Package.swift file's dependencies.


Add pod 'Yams' to your Podfile.


Add github "jpsim/Yams" to your Cartfile.


Yams has three groups of conversion APIs: one for use with Codable types, another for Swift Standard Library types, and a third one for a Yams-native representation.

Codable types

  • Codable is an encoding & decoding strategy introduced in Swift 4 enabling easy conversion between YAML and other Encoders like JSONEncoder and PropertyListEncoder.
  • Lowest computational overhead, equivalent to Yams.Node.
  • Encoding: YAMLEncoder.encode(_:) Produces a YAML String from an instance of type conforming to Encodable.
  • Decoding: YAMLDecoder.decode(_:from:) Decodes an instance of type conforming to Decodable from YAML String.
import Foundation
import Yams

struct S: Codable {
    var p: String

let s = S(p: "test")
let encoder = YAMLEncoder()
let encodedYAML = try encoder.encode(s)
encodedYAML == """
p: test

let decoder = YAMLDecoder()
let decoded = try decoder.decode(S.self, from: encodedYAML)
s.p == decoded.p

Swift Standard Library types

  • The type of Swift Standard Library is inferred from the contents of the internal Yams.Node representation by matching regular expressions.
  • This method has the largest computational overhead When decoding YAML, because the type inference of all objects is done up-front.
  • It may be easier to use in such a way as to handle objects created from JSONSerialization or if the input is already standard library types (Any, Dictionary, Array, etc.).
  • Encoding: Yams.dump(object:) Produces a YAML String from an instance of Swift Standard Library types.
  • Decoding: Yams.load(yaml:) Produces an instance of Swift Standard Library types as Any from YAML String.
// [String: Any]
let dictionary: [String: Any] = ["key": "value"]
let mapYAML: String = try Yams.dump(object: dictionary)
mapYAML == """
key: value

let loadedDictionary = try Yams.load(yaml: mapYAML) as? [String: Any]

// [Any]
let array: [Int] = [1, 2, 3]
let sequenceYAML: String = try Yams.dump(object: array)
sequenceYAML == """
- 1
- 2
- 3

let loadedArray: [Int]? = try Yams.load(yaml: sequenceYAML) as? [Int]

// Any
let string = "string"
let scalarYAML: String = try Yams.dump(object: string)
scalarYAML == """

let loadedString: String? = try Yams.load(yaml: scalarYAML) as? String


  • Yams' native model representing Nodes of YAML which provides all functions such as detection and customization of the YAML format.
  • Depending on how it is used, computational overhead can be minimized.
  • Encoding: Yams.serialize(node:) Produces a YAML String from an instance of Node.
  • Decoding Yams.compose(yaml:) Produces an instance of Node from YAML String.
var map: Yams.Node = [
    "array": [
        1, 2, 3
map.mapping?.style = .flow
map["array"]?.sequence?.style = .flow
let yaml = try Yams.serialize(node: map)
yaml == """
{array: [1, 2, 3]}

let node = try Yams.compose(yaml: yaml)
map == node


Both Yams and libYAML are MIT licensed.


Stars: 478



2.0.0 - 2019-04-06 23:48:52

  • Change byteOffset to offset in YamlError.reader.
    Norio Nomura
  • Add encoding option to Parser as Parser.Encoding type to specify which encoding to pass to libYAML. Along with that change, add encoding options to load(), load_all(), compose(), compose_all() and YAMLDecoder. The default encoding will be determined at run time based on the String type's native encoding.
    Norio Nomura
Bug Fixes
  • None.

1.0.2 - 2019-04-01 17:53:55

  • None.
  • Update LibYAML sources to latest versions as of January 6 2018.
    JP Simard
Bug Fixes
  • Fix some test failures with the latest Swift 5 snapshot on Apple platforms.
    Norio Nomura #143

  • Preserve nanoseconds in dates when using swift-corelibs-foundation with Swift 5.
    Norio Nomura #146

  • Fix null/~/NULL/Null were parsed as strings, not nil by YAMLDecoder.
    Norio Nomura #157

1.0.1 - 2018-08-30 20:29:33

  • None.
  • Improve support for compiling with Swift 4.2 or later.
    Norio Nomura
Bug Fixes
  • Fix issues with unset DYLIB_COMPATIBILITY_VERSION and DYLIB_CURRENT_VERSION. Now both values are set to 1.
    Norio Nomura #131

1.0.0 - 2018-05-19 01:42:55

  • Rename ScalarRepresentableCustomizedForCodable to YAMLEncodable.
    Norio Nomura
Bug Fixes
  • None.