The toEncoding function is not used for YAML but is for JSON.

[philderbeast]

To encode JSON and specify the field order or rename fields, there's a way to do this using toEncoding ...

Encoding is ordered because it's just a Builder under the hood. So, if you write something like

instance ToJSON X where
toEncoding X{..} = pairs ("b" .= xB <> "a" .= xA)
the order is going to be {"b": ..., "a": ...}.
SOURCE: Object is unordered

This does not work when encoding to YAML ...

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE RecordWildCards #-}
{-# LANGUAGE OverloadedStrings #-}

type SpeedSection = Maybe (Integer, Integer)

data Task =
    Task { taskName :: Name
         , speedSection :: SpeedSection
         , zones :: [Turnpoint]
         } deriving (Eq, Show, Generic)

instance ToJSON Task where
    toEncoding Task{..} =
        pairs ( "zones#1" .= zones
              <> "taskName#2" .= taskName
              <> "speedSection#3" .= speedSection
              )

> let a = Task "AA" Nothing []
> Data.Aeson.encode a
"{\"zones#1\":[],\"taskName#2\":\"AA\",\"speedSection#3\":null}"
> Data.Yaml.encode a
"taskName: AA\nzones: []\nspeedSection: null\n"

The yaml package docs mention the toEncoding function. Please add a note about this unexpected behaviour.

Can the encoding to YAML be made to use the renames and reordering the way encoding to JSON does?

[philderbeast]

As toEncoding is not used, perhaps the renaming effect can be had using toJSON ...

instance ToJSON Task where
    toJSON Task{..} =
        object [ "zones#1" .= zones
               , "taskName#2" .= taskName
               , "speedSection#3" .= speedSection
               ]

> Data.Aeson.encode a
"{\"zones#1\":[],\"taskName#2\":\"AA\",\"speedSection#3\":null}"
> Data.Yaml.encode a
"zones#1: []\ntaskName#2: AA\nspeedSection#3: null\n"

[philderbeast]

The ordering effect cannot be had using toJSON ...

instance ToJSON Task where
    toJSON Task{..} =
        object [ "taskName#1" .= taskName
               , "speedSection#2" .= speedSection
               , "zones#3" .= zones
               ]

> Data.Aeson.encode a
"{\"speedSection#2\":null,\"taskName#1\":\"AA\",\"zones#3\":[]}"
> Data.Yaml.encode a
"speedSection#2: null\ntaskName#1: AA\nzones#3: []\n"

[snoyberg]

Doc improvements are always welcome via a pull request. However, there's no way for the yaml package to take advantage of the toEncoding field, since it embeds a JSON encoding within. If you'd like to control ordering, please see the Text.Libyaml module, which is more low-level.

[philderbeast]

I've seen code snippets where compare is used for the ordering.

https://gist.github.com/tfausak/52e4560cbe175a84fd30?L25#file-ppy-hs-L26

I've tried this, setting deriving (Eq, Ord) on all records and field types. The resulting order I see then is alphabetical in field order. What I want is a structural layout ordering that matches the field order of the records as they're defined.

[snoyberg]

In order to achieve this, I believe you'll need to use the Text.Libyaml layer, which does not encoding via Data.Aeson.Value. The latter forces arbitrary ordering.