Here's an example of using @JsonSetter annotations as a "preprocessor"-like way to move clients using old API while still being able to update Orca's internal model.

JsonSetterSpec.groovy

/*
 * Copyright 2016 Google, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License")
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.netflix.spinnaker.orca.clouddriver

import com.fasterxml.jackson.annotation.JsonSetter
import com.fasterxml.jackson.databind.ObjectMapper
import groovy.transform.Canonical
import spock.lang.Specification

class MixinTest extends Specification {

  def "should pass"() {
    given:
      ObjectMapper mapper = new ObjectMapper()

    when:
      Pojo result = mapper.readValue("{\"region\": \"foo\"}", Pojo)

    then:
      result
      result.regions == ["foo"]

    when:
      result = mapper.readValue("{\"regions\": [\"foo\", \"bar\"]}", Pojo)

    then:
      result
      result.regions == ["foo", "bar"]

    when:
      result = mapper.readValue("{\"someOlderApiValue\": [\"foo\", \"bar\"]}", Pojo)

    then:
      result
      result.regions == ["foo", "bar"]
  }

  @Canonical
  static class Pojo {
    // Most up-to-date model
    List<String> regions

    // Older model values that need to be converted to the the "Most up-to-date" model.
    @JsonSetter("region")
    String fromRegion(String r) {
      regions = [r]
    }

    @JsonSetter("someOlderApiValue")
    String fromSomeOlderApiValue(List l) {
      regions = l
    }
  }
}

@cfieber, @ajordens

The biggest downside would be having to create a POJO for every input for every stage. Some stages already use StageData, which does have some @deprecated fields that could use this technique.

@duftler as FYI too.

This is a start (and probably better than explicitly having to handle all possible scenarios).

Part of me could see this happen closer to the edge ... imagine something that runs as part of the PipelineBuilder lifecycle and does conversions prior to anything actually being executed or persisted.

If conversions are done upfront, than there's at least consistency between what is being executed and what is stored. It also provides an opportunity to more generically modify payloads (say region -> regions across the board) ... rather than requiring individual stages to do it each time.