Consider design/implementation of consistent format for "networked $THING with attachments"
- Dominant language
- TypeScript
- Stars
- 38
- Forks
- 22
- PR merge metrics
- No merged PRs in 30d
Description
## Background
There are a few similar concepts that fall into this category:
1. **Form:**
- $THING: Form definition (ODK XForms XML)
- attachments: anything specified to be referenced by `jr:` URL
Currently, we handle this by parsing the form XML, identifying the resources, and calling a client-defined `fetch`-like function to retrieve the attachments.
2. **Instance** (outgoing for submission):
- $THING: Instance XML, as serialized from form state
- attachments: any file/upload data associated with a form question's value state, serialized as files separately from the instance XML (their respective nodes serialized with their respective file names)
Currently, we handle this by building a (subclass/subtype of) [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). The design of this web standard is closely analogous to [`multipart/form-data` HTTP semantics](https://datatracker.ietf.org/doc/html/rfc7578).
3. **Form and instance** (incoming for edit):
- $THING (1): As in item 1
- attachments (1): As in item 1
- $THING (2): As in item 2
- attachments (2): As in item 2
A serialized instance and its attachments does not contain sufficient information to initialize form state, we actually need the superset of items 1 & 2 to do that. We are currently designing an additive interface in #299, angling toward a solution conceptually similar but slightly different to the solutions for item 1 (and less similar to the solution for item 2, but likewise conceptually related notwithstanding network concerns).
I'm posting this now because the solution we're angling toward in #299 is _probably right_, but it _smells really suspicious_ to have three similar-but-different solutions for the same general concept.
That smell is especially strong when we look at the prior art in item 2. Our solution there roughly corresponds to two HTTP transport designs, both having strengths in terms of reflecting HTTP semantics as a well worn path for expressing this kind of pattern.
## Generalization: hypertext
I want to make this proposal as loose as possible, focused mainly on the underlying principles. In all three cases we have:
1. One or more document resources, each of which is incomplete or drastically limited without...
2. ... N ancillary resources, referenced by those documents.
We expect to load those ancillary resources (approximately) _immediately_, and (at least potentially) _concurrently_.
This is pretty much verbatim how one might describe "hypertext". I think it would be very compelling to define a meta-spec that wraps these bundle-y concepts up with consistent use of standard HTTP concepts.
Some pertinent concepts (non-exhaustive! not meant to be proscriptive!):
- As with outgoing instance submission, `multipart/form-data` _might_ be conceptually pertinent. It is a suitable bidirectional payload format, capable of expressing the **bare minimum** requirements for every case considered above to function. However, multipart (alone) would tend to be in conflict with potential for concurrent loading.
- Another standard for referencing related resources in an HTTP payload is the [`Link` header](https://datatracker.ietf.org/doc/html/rfc8288). This would _facilitate both_ immediate and concurrent loading.
## Supplementary to existing solutions
If we were to explore this concept, it would _necessarily_ be supplementary to existing solutions. The Web Forms project isn't in a position to impose some new HTTP-based spec on integrators. For that matter, if we were to pursue something like this, we'd want to do it in collaboration with existing or interested integrators. But we'd need to continue supporting existing usage patterns in the meantime, and probably indefinitely.
The goal here isn't to replace existing concepts, but to think about how we could supplement them with a coherent design for each of these rather similar cases... and ideally without introducing [yet another competing standard](https://xkcd.com/927/) in the process.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the additive interface proposed in issue #299 and the existing handling for form XML attachments, FormData-based submissions, and incoming form-and-instance edits. A useful outcome would be an agreed supplementary design that addresses all three cases consistently, but this issue does not define an implementation scope or specific files and tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100