Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Shards and Web

JSON and YAML in Crystal

Work with JSON and YAML in Crystal: JSON.parse and JSON::Any, to_json, JSON::Serializable with field options, YAML, error handling and Ruby stand-ins.

Almost every program has to read or write structured text. Crystal's standard library includes JSON and YAML, and both offer two styles: a dynamic one that returns a loose tree (JSON::Any) and a typed one that maps documents straight into your own classes (JSON::Serializable, YAML::Serializable). The typed style is the one that makes Crystal special: the mapping code is generated by macros, so it is fast and checked by the compiler.

The compiler is not available on this site. Crystal code is read-only, and each section has a Ruby stand-in that parses the same documents.

Parsing dynamically with JSON::Any

CRYSTAL
require "json"

text = %({"name": "Ada", "age": 36, "langs": ["Crystal", "Ruby"], "address": {"city": "London"}})

data = JSON.parse(text)           # JSON::Any
data["name"].as_s                 # "Ada"
data["age"].as_i                  # 36
data["langs"][0].as_s             # "Crystal"
data["address"]["city"].as_s      # "London"
data["missing"]?                  # nil  (the ? returns nil instead of raising)
data["langs"].as_a.map(&.as_s)    # ["Crystal", "Ruby"]

JSON::Any wraps any JSON value. You must say what you expect with as_s, as_i, as_f, as_bool, as_a (array) or as_h (hash). If the value has another type, the call raises, and as_s? and friends return nil. The ["key"] / ["key"]? split follows the same rule as for hashes (see Hashes, Tuples and Named Tuples).

Ruby Ruby stand-in: parse and navigate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Writing JSON

CRYSTAL
{name: "Ada", age: 36}.to_json           # {"name":"Ada","age":36}
[1, 2, 3].to_json                        # [1,2,3]
"hi \"there\"".to_json                   # "hi \"there\""

pretty = JSON.build(indent: 2) do |json|
  json.object do
    json.field "name", "Ada"
    json.field "langs" do
      json.array do
        json.string "Crystal"
        json.string "Ruby"
      end
    end
  end
end

Most basic types have to_json. For large output, JSON.build and to_json(io) write directly to an IO, avoiding a big intermediate string. JSON.build(indent: 2) produces readable output.

Typed mapping with JSON::Serializable

Include JSON::Serializable in a class or struct and its instance variables become the JSON fields:

CRYSTAL
require "json"

class User
  include JSON::Serializable

  getter name : String
  getter age : Int32
  getter email : String?                    # optional: may be missing or null
  getter langs : Array(String) = [] of String

  @[JSON::Field(key: "is_admin")]
  getter admin : Bool = false

  @[JSON::Field(ignore: true)]
  property session_token : String?
end

user = User.from_json(%({"name":"Ada","age":36,"is_admin":true}))
user.name       # "Ada"  (a String, not JSON::Any)
user.email      # nil
user.admin      # true
user.to_json    # {"name":"Ada","age":36,"langs":[],"is_admin":true}

User.from_json(%({"name":"Ada"}))
# raises JSON::SerializableError: Missing JSON attribute: age

The type annotations are a contract. A missing required field, or "age": "old", raises JSON::ParseException/JSON::SerializableError with the position and field name, so bad input is rejected at the boundary and never travels into your program. Useful JSON::Field options: key: (rename), ignore:, emit_null: (write null fields), converter: (custom parsing, such as Time::Format) and root: (unwrap an object).

Nested types and arrays work automatically: a getter address : Address where Address also includes JSON::Serializable. Use use_json_discriminator for unions of classes selected by a "type" field.

Ruby Ruby stand-in: a typed loader that validates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

YAML

The API mirrors JSON. YAML.parse returns YAML::Any, and YAML::Serializable maps into classes:

CRYSTAL
require "yaml"

text = <<-YAML
  name: my_app
  port: 3000
  features:
    - search
    - billing
  database:
    host: localhost
    pool: 5
YAML

config = YAML.parse(text)
config["port"].as_i                      # 3000
config["features"].as_a.map(&.as_s)      # ["search", "billing"]

class Database
  include YAML::Serializable
  property host : String
  property pool : Int32 = 5
end

class Config
  include YAML::Serializable
  property name : String
  property port : Int32
  property features : Array(String)
  property database : Database
end

cfg = Config.from_yaml(text)
cfg.database.host        # "localhost"
puts cfg.to_yaml

YAML is used for shard.yml (Shards and Dependencies), application configuration and fixtures. It is friendlier for humans than JSON but has more pitfalls: indentation matters, and unquoted values such as no, 1.10 or 0123 may be read as a boolean, a float or an octal number in some parsers. Quote anything that must stay a string.

Ruby Ruby stand-in: YAML config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Choosing between the styles

flowchart TD
  A["Incoming JSON or YAML"] --> B{"Is the shape known?"}
  B -->|yes| C["Serializable class: validated, typed, fast"]
  B -->|no or partly| D["JSON::Any / YAML::Any: explore with as_s, as_i"]

Use typed mapping whenever you know the shape; fall back to Any for unknown documents.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does data["missing"]? return on a JSON::Any object?

    The ? form returns nil for a missing key instead of raising.
  2. 2. What does include JSON::Serializable do?

    A macro reads the instance variables at compile time and writes the from_json and to_json methods.
  3. 3. What happens if a required field such as age : Int32 is missing from the input?

    Only nilable types or fields with defaults may be missing.
  4. 4. How do you map the JSON key is_admin to a property called admin?

    JSON::Field(key: ...) sets the external name.

Summary

  • JSON.parse and YAML.parse return loose Any values; convert with as_s, as_i, as_a, as_h.
  • to_json and JSON.build write JSON; to_yaml writes YAML.
  • JSON::Serializable and YAML::Serializable map documents to typed classes and reject bad input.
  • Annotations such as JSON::Field(key:) rename or skip fields.
  • Quote YAML strings that look like other types.

Next: Testing with Spec