# Spec proposal: Media in external secondary intances

**URL:** <https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567>\
**Category:** Development\
**Created:** [September 16, 2026, 12:34pm UTC](https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567 "2026-09-16T12:34:10Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![seadowg](https://getodk.b-cdn.net/user_avatar/forum.getodk.org/seadowg/32/10045_2.png) [@seadowg](https://forum.getodk.org/u/seadowg)\
**Post date:** [September 16, 2026, 12:34pm UTC](https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567/1 "2026-09-16T12:34:10Z")

</div>

The ODK core team would like to add support for referencing form media (images, audio and video) in external secondary instances that can be used in the form in select options, defaults and as question answers. This is the first part of a set changes that should eventually add support for entity media.

# Changes

The changes proposed are:

## XForm

1. Additional specification around how non `jr://` links should be handled by clients when used in as question/select media, defaults or as question answers (the latter including "dynamic defaults"). A value like `myFile.jpg` should be treated as a relative path for either form media (equivalent to `jr://<type>/myFile.jpg`) or instance media (`<instance media dir>/myFile.jpg`). Clients should first attempt to load form media and then fallback to instance media if no form media exists for the given value.

2. Add a `reference` attribute to value nodes within `text` (for `itext`). If `true`, it indicates to a client that the element value is a column mapping, as opposed to a literal value to be used directly:

## XLSForm

Add a new sheet `secondary_instances` that allows configuring media/translation column mappings for secondary instances:

| name | label | image | image::English (en) | audio::French (fr) |
| --- | --- | --- | --- | --- |
| c1 | label | image | image\_en | audio\_fr |

This will create the `/itext/translation/text/` nodes required (as detailed above) which will be identified as `<instance_name>-itemset:label` from the `itemset` in question nodes for `select_one_from_file`:

```xml
<select1 ref="/test_name/q1">
  <label ref="jr:itext('/test_name/q1:label)"l/>
  <itemset nodeset="instance('c1')/root/item">
    <value ref="name"/>
    <label ref="jr:itext('c1-itemset:label’)" />
  </itemset>
</select1>

```

# Future expansion

- The `secondary_instances` sheet could have a column that defines the actual csv file name for the instance allowing name to act as an identifier for the configuration rather than the file and the identifier. This would unlock having different column configurations for different questions.
- The XForm generated by XLSForm for internal and external selects use `itext` slightly differently. In the future, internal selects could adopt the approach being proposed here as well.

---

<div class="post-metadata">

**Author:** ![seadowg](https://getodk.b-cdn.net/user_avatar/forum.getodk.org/seadowg/32/10045_2.png) [@seadowg](https://forum.getodk.org/u/seadowg)\
**Post date:** [September 16, 2026, 12:42pm UTC](https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567/2 "2026-09-16T12:42:17Z")

</div>

I just wanted to also add a quick note on Central's support for uploading media that's referenced by a secondary instance rather than the form itself: for clients to be able to download media files referenced by an external secondary instance, Central will either need to stop gating against arbitrary media file uploads or process the secondary instance in some way to determine the additional media files that can be uploaded. Whichever way this ends up working is a detail of Central's feature set rather than a change to any specification however, so I've not mentioned it in the main text above.

---

<div class="post-metadata">

**Author:** ![ahblake](https://getodk.b-cdn.net/user_avatar/forum.getodk.org/ahblake/32/22392_2.png) [@ahblake](https://forum.getodk.org/u/ahblake)\
**Post date:** [September 17, 2026, 10:33pm UTC](https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567/3 "2026-09-17T22:33:37Z")

</div>

I am super excited about this, the eventual linking of media with entities opens up so many options and removes a lot of additional workarounds.

Eagerly watching this space 🙂

> [@seadowg](#):
>
> Central's support for uploading media that's referenced by a secondary instance rather than the form itself:

Does this mean that media would still be uploaded (and duplicated) against all forms that reference the external instance, at least initially?

---

<div class="post-metadata">

**Author:** ![seadowg](https://getodk.b-cdn.net/user_avatar/forum.getodk.org/seadowg/32/10045_2.png) [@seadowg](https://forum.getodk.org/u/seadowg)\
**Post date:** [September 18, 2026, 7:21am UTC](https://forum.getodk.org/t/spec-proposal-media-in-external-secondary-intances/58567/4 "2026-09-18T07:21:03Z")

</div>

> [@ahblake](#):
>
> Does this mean that media would still be uploaded (and duplicated) against all forms that reference the external instance, at least initially?

It depends on how it's implemented in Central, but I imagine that can be optimized in the future.
