It may not look like it but it's just as explicit in YAML as it is in JSON. In fact JSON is valid YAML even: http://viewsourcecode.org/why/redhanded/inspect/yamlIsJson.h...

YAML has a couple big advantages (in the proper situations) over JSON. Self-referencing, complex datatypes, and (my personal favorite) embedded block literals. I've, perhaps unwisely, embedded entire webpages a single indentation level after a variable and retained all of its formatting.

I'm no YAML zealot though, I do use JSON most of the time, but in the past couple years I've started writing most of my config files in YAML where I have the opportunity.

We recently moved much of our application's schema definitions and configurations out of code/JSON and into YAML files (we generate JSON during the build process in placess where it is necessary). A pleasant side effect was that the YAML file set began to double as basic documentation.

e.g.

    name: user
    plural: users
    label: User
    ...
    primary_key: uid
    display_key: full_name
    unique_keys:
        - username
        - uid
    client:
        storage:
            type: IndexedDB
    ...
        actions:
            create:
                label: Save
                permission: create_user
    ...
    server:
        storage:
            type: mysql
    ...
        api:
            create_user:
                url: /users
                method: post
    fields:
        username:
            name: username
            label: Username
            type: string
            length: 20
            required: true
            editable: false

This is very interesting.

So is this the equivalent of multiple JSON documents? I'm looking at:

http://yaml.org/spec/1.1/#id857577 and http://yaml.org/spec/1.1/#stream/information%20model

I'm actually having a hard time, even with some google-fu, finding information about how this might be used. YAML->json parsers have failed to handle docs with a '...' separating parts of a document so far. Would this triple-dot structure be used to create multiple JS objects? How would I find more information about how this might be used in practice?

I have a feeling this would be easier to figure out if I just went and played around with it in practice, but it also seems like something that could be documented in more beginner-friendly terms.

I'll probably be kicking myself once I figure it out, but I also only have a cursory understanding of how streams work. Maybe this is an opportunity to fix that. Once I figure it out, I'll respond to this if nobody else has.

I think the GP was using '...' as a standard "stuff removed for brevity" ellipsis.

However, since you asked:

In a YAML document, there is an implicit top-level object, either a hash/dict/associative array or a list/array depending on your formatting.

The '...' separates streams, or top-level objects, within a single file or IO stream.

YAML parsers generally stop when they hit the separator, even in languages that can do multiple assignment. If your IO stream behaves like a file handle, you can read it repeatedly into different variables until EOF.

Multiple streams in a YAML document are fairly uncommon. I think most people don't know they exist, but I appreciate the flexibility and use it whenever it makes sense.

Actually the '...' is for parts I've omitted for brevity.