Proposal: Add option `getOptions(): JsonReader.Options` function to JsonAdapter.

[ZacSweers]

This would allow easy querying of what properties an adapter intends to read, unlocking the ability to easily track unknown properties.

abstract class JsonAdapter<T> {
  /** Returns the available Options this adapter looks for in parsing. Null if undefined. */
  val options: JsonReader.Options? = null
}

class MyRecordingFactory : JsonAdapter.Factory {
  override fun create(type: Type, annotations: Set<Annotation>, moshi: Moshi): JsonAdapter<*> {
    // Look for some opt-in
    if (type is Class<*> && type.isAnnotationPresent(TrackUnknownProperties::class.java) {
      val delegate = moshi.nextAdapter<Any>(this, type, annotations)
      val options = delegate.options?.strings()?.toSet() ?: return delegate
      return object : JsonAdapter<Any> {
        override fun fromJson(reader: JsonReader): Any {
          val jsonValue = reader.readJsonValue() as Map<String, *>
          val unknownKeys = jsonValue.keys.filterNot { it in options }
          if (unknownKeys.isNotEmpty()) {
            // Report unknown keys!
          }
          
          return delegate.fromJsonValue(jsonValue
        }
      }
    }
  }
}

If we don't want this as a dedicated API, we could also make it a special-cased subclass

abstract class OptionsJsonAdapter<T> : JsonAdapter<T>() {
  /** Returns the available Options this adapter looks for in parsing. Null if undefined. */
  val options: JsonReader.Options? = null
}

Or we could remove options from the API entirely and make it simple strings

abstract class JsonAdapter<T> {
  /** Returns the available names this adapter looks for in parsing. Null if undefined. */
  val names: Set<String>? = null
}

[ZacSweers]

I believe this would be a good solution for cases like #575 and rharter/auto-value-moshi#109. Still left to an implementing adapter, but makes it trivial to implement since all the data is there in most cases

[JakeWharton]

All of these are very weird to me. JsonAdapter is intentionally opaque to what underlying JSON it reads and writes. Even if you assert that a majority of adapters read static object structures, there's still a swath of adapters which read other structures, are dynamic, or compose multiple adapters. What do those return?

It's very asymmetric to expose such an API on JsonAdapter.

[ZacSweers]

Those would return null to indicate they can't offer that kind of information. Considering this is available to both read/write, I don't follow the symmetry concern. Could you unpack that a bit?

[ZacSweers]

Alternatively, if the concern is having it in the top-level API, it could just be an interface that's adapters that support it can optionally implement.

[JakeWharton]

The asymmetry is with the format types. Adapter is purposefully opaque and generic such that each could read and write any JSON type–even multiple.

This is akin to Java's List having a boolean containsStrings() function on it. Sure some lists contains strings, but the need to ask that question of a List is weird and wrong. Moreover, would I return true for heterogeneous lists? It's not even clear what answering such a question means because you have no context as to the caller's intent with such information.

The interface is at least a start since it keeps the adapter API clean. Can the interface live in whatever library wants to read the information?

[ZacSweers]

I'd want to propose this in Moshi directly since most cases using it would rely on the built-in reflection adapters or generated ones implementing it. Something like ObjectJsonAdapter maybe?