Confusion around geo.country_iso_code vs country_code2

When we parse an IP for geo info using:

geoip {
  source => "ip"
  target => "client"
  fields => ["location", "country_code2", "country_name"]
}

LogStash creates documents with:

client: {
   geo: {
     country_iso_code: "ZW"
   }
}

Note the mysterious country_iso_code and no country_code2.
When we change the field name in the filter:

geoip {
  source => "ip"
  target => "client"
  fields => ["location", "country_iso_code", "country_name"]
}

LogStash balks with the following error:

Pipeline error {:pipeline_id=>"mybuhler-logs", :exception=>java.lang.IllegalArgumentException: illegal field value country_iso_code. valid values are [AUTONOMOUS_SYSTEM_NUMBER, AUTONOMOUS_SYSTEM_ORGANIZATION, CITY_NAME, COUNTRY_NAME, CONTINENT_CODE, CONTINENT_NAME, COUNTRY_CODE2, COUNTRY_CODE3, DOMAIN, IP, ISP, POSTAL_CODE, DMA_CODE, REGION_NAME, REGION_CODE, REGION_ISO_CODE, TIMEZONE, LOCATION, LATITUDE, LONGITUDE, ORGANIZATION], :backtrace=>["org.logstash.filters.geoip.Fields.parseField(org/logstash/filters/geoip/Fields.java:123)", "org.logstash.filters.geoip.GeoIPFilter.createDesiredFields(org/logstash/filters/geoip/GeoIPFilter.java:138)", "org.logstash.filters.geoip.GeoIPFilter.(org/logstash/filters/geoip/GeoIPFilter.java:94)", "jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)", "jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(jdk/internal/reflect/NativeConstructorAccessorImpl.java:62)", "jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(jdk/internal/reflect/DelegatingConstructorAccessorImpl.java:45)", "java.lang.reflect.Constructor.newInstance(java/lang/reflect/Constructor.java:490)", "org.jruby.javasupport.JavaConstructor.newInstanceDirect(org/jruby/javasupport/JavaConstructor.java:253)", "org.jruby.RubyClass.newInstance(org/jruby/RubyClass.java:939)", "org.jruby.RubyClass$INVOKER$i$newInstance.call(org/jruby/RubyClass$INVOKER$i$newInstance.gen)", "usr.share.logstash.vendor.bundle.jruby.$2_dot_5_dot_0.gems.logstash_minus_filter_minus_geoip_minus_7_dot_2_dot_12_minus_java.lib.logstash.filters.geoip.setup_filter(/usr/share/logstash/vendor/bundle/jruby/2.5.0/gems/logstash-filter-geoip-7.2.12-java/lib/logstash/filters/geoip.rb:152)", "usr.share.logstash.vendor.bundle.jruby.$2_dot_5_dot_0.gems.logstash_minus_filter_minus_geoip_minus_7_dot_2_dot_12_minus_java.lib.logstash.filters.geoip.register(/usr/share/logstash/vendor/bundle/jruby/2.5.0/gems/logstash-filter-geoip-7.2.12-java/lib/logstash/filters/geoip.rb:109)", "org.jruby.RubyClass.finvoke(org/jruby/RubyClass.java:572)", "org.jruby.RubyBasicObject.callMethod(org/jruby/RubyBasicObject.java:354)", "org.logstash.config.ir.compiler.FilterDelegatorExt.doRegister(org/logstash/config/ir/compiler/FilterDelegatorExt.java:88)", "org.logstash.config.ir.compiler.AbstractFilterDelegatorExt.register(org/logstash/config/ir/compiler/AbstractFilterDelegatorExt.java:75)", "org.logstash.config.ir.compiler.AbstractFilterDelegatorExt$INVOKER$i$0$0$register.call(org/logstash/config/ir/compiler/AbstractFilterDelegatorExt$INVOKER$i$0$0$register.gen)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.register_plugins(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:233)", "org.jruby.RubyArray.each(org/jruby/RubyArray.java:1821)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.register_plugins(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:232)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.maybe_setup_out_plugins(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:599)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.start_workers(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:245)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.run(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:190)", "usr.share.logstash.logstash_minus_core.lib.logstash.java_pipeline.start(/usr/share/logstash/logstash-core/lib/logstash/java_pipeline.rb:142)", "org.jruby.RubyProc.call(org/jruby/RubyProc.java:318)", "java.lang.Thread.run(java/lang/Thread.java:829)"], "pipeline.sources"=>["/etc/logstash/conf.d/mybuhler-logs/010-input-kafka.conf", "/etc/logstash/conf.d/mybuhler-logs/300-filter.conf", "/etc/logstash/conf.d/mybuhler-logs/350-ecs.conf", "/etc/logstash/conf.d/mybuhler-logs/400-filter_email.conf", "/etc/logstash/conf.d/mybuhler-logs/900-output-es.conf"], :thread=>"#<Thread:0x212ac690 run>"}

According to the ecs docs the official name of the field is country_iso_code so why won't LogStash/Elastic use it?

Logstash 8.2

There is a mapping from the name that has been used in the past to the ECS compatible name. So the short answer is "backwards compatibility".

Backwards compatibility explains why I can use the old field name, not why I can't use the new field name...