Detail the JSON getter design options.

This sketches the consideration for adding `apply()` methods to JSON,
together with potential alternatives.

ponylang/ponyc#3922

Author: sgebbie

text/0000-json-getters.md

@@ -10,39 +10,126 @@ Introduce "getters" into the JSON package. Specifically access methods for
 
 # Motivation
 
-TODO Why are we doing this? What use cases does it support? What is the expected outcome?
+Currently the interaction between the JSON API and the Pony reference
+capability type system makes it difficult to work with JSON documents that need
+to be mutated after they have been created.
+
+By introducing getter methods it will be possible to leverage viewpoint
+adaptation to enable mutations when the caller site holds a mutable reference,
+but to enforce immutability when the calling alias is a `val` or `box`.
+
+Additionally, a caller with an `iso` reference will be able to perform
+mutations to the document and then recover and `iso` reference afterwards.
 
 # Detailed design
 
-TODO This is the bulk of the RFC. Explain the design in enough detail for somebody familiar with the language to understand, and for somebody familiar with the compiler to implement. This should get into specifics and corner-cases, and include examples of how the feature is used.
+The implementation consists of using the `apply()` style access to introducing
+three getters, into `JsonDoc`, `JsonObject` and `JsonArray` respectively:
 
-# How We Teach This
+- document data access: `fun apply(): this->JsonType! => ...`,
+- object data access: `fun apply(): this->Array[JsonType]! => ...`,
+- array data access: `fun apply(): this->Map[String, JsonType]! => ...`.
+
+These access methods can then be used via direct calls or via syntactic sugar
+calls.
 
-TODO What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing Pony patterns, or as a wholly new one?
+# How We Teach This
 
-Would the acceptance of this proposal mean the Pony guides must be re-organized or altered? Does it change how Pony is taught to new users at any level?
+The examples in the JSON inline documentation can be extended or changed to
+demonstrate the usage of the getter methods.
 
-How should this feature be introduced and taught to existing Pony users?
+The access methods, themselves, will be documented.
 
 # How We Test This
 
-TODO How do we assure that the initial implementation works? How do we assure going forward that the new functionality works after people make changes? Do we need unit tests? Something more sophisticated? What's the scope of testing? Does this change impact the testing of other parts of Pony? Is our standard CI coverage sufficient to test this change? Is manual intervention required?
-
-In general this section should be able to serve as acceptance criteria for any implementation of the RFC.
+Unit tests that cover both mutable access and immutable access, as well is the
+recovery of `iso` documents after mutation.
 
 # Drawbacks
 
-TODO Why should we *not* do this? Things you might want to note:
+This is a purely additive change, so it does not incur in major risk in terms of
+existing code. Additionally, the code complexity is low and should be easy to
+maintain.
+
+## Uptake and entrenchment
+
+However, if there is uptake following these additions, the approach will likely
+become entrenched, and therefore difficult to revert. Therefore, we need to be
+comfortable with this approach going forward.
 
-* Breaks existing code
-* Introduces instability into the compiler and or runtime which will result in bugs we are going to spend time tracking down
-* Maintenance cost of added code
+## Syntactic sugar oddities
+
+By relying on the `apply()` syntactic sugar it is possible to write expressions
+that are a little contrived:
+
+```pony
+(jdoc_ref() as JsonObject)()("other_stuff") = "hello"
+```
+
+which might be more easily read if written as:
+
+```pony
+(jdoc_ref() as JsonObject).apply()("other_stuff") = "hello"
+```
 
 # Alternatives
 
-TODO What other designs have been considered? What is the impact of not doing this?
-None is not an acceptable answer. There is always to option of not implementing the RFC.
+The basic approach of adding "getter" access methods seems quite reasonable.
+However, the issue of method naming is really the point where alternative could
+be considered.
+
+## The current recommendation
+
+A purely additive change using the `apply()` syntactic sugar for access. This
+allows one to write:
+
+```pony
+try
+  let obj = (json_doc() as JsonObject)
+  obj()("more") = "stuff"
+end
+```
+
+## Additionally include `update()`
+
+That is, include an `update(value: JsonDoc): this->JsonType! => ...` method to
+allow for setting the underlying `data` field.
+
+## Convert the `data` field to private
+
+The above recommendation is a non-breaking change. Therefore, the current `data`
+field, which is public has be left as-is. However, it might be better
+standardise on using the access methods and make the data field private. That
+is, rename the field to:
+
+- `_data`
+
+The drawbacks of this approach are:
+
+- it becomes a breaking change for all existing code,
+- it would require the addition of a setter (such as introducing `update(...)`).
+
+## Use `data()` as the access method
+
+If make the data field private, we can consider using `data` as the access
+method name. In this case we would not provide the syntactic sugar, but we would
+still solve the core problem of data mutation.
+
+However, the drawback of this approach is that a separate "setter" may be
+needed.
+
+## Dual access with `apply()` and `data()`
+
+Given that the syntactic sugar approach can sometime look odd, we could consider
+providing both `apply()` and `data()`. However, the drawbacks of this approach
+are:
+
+- it burdens the API user with the choice of calling `data()` or using the sugar
+  (or even calling `apply()`,
+- it would still require providing a setter of some form.
+
 
 # Unresolved questions
 
-TODO What parts of the design are still TBD?
+Should a deeper design review be carried out? Otherwise, the alternatives,
+above, should cover the bulk of the potential questions.