Working with RSMF files built outside Relativity

RSMF is an open container format that you can build with any tool outside of Relativity. Common sources include forensic suites, third-party collection applications, and in-house scripts. Relativity can ingest and render these externally built RSMF files, but the Short Message Viewer can only display the data that the external builder included in the RSMF manifest. If the manifest is missing elements, those elements do not appear in the viewer. This topic covers how Relativity renders externally built RSMF files, how to validate them, and how attachment linking works. It also describes the supported manifest elements and options for remediating missing content.

Related topics:

• Processing an RSMF file
• RSMF field reference
• Short message conversion overview

How Relativity renders an externally built RSMF (rendering contract)

Relativity renders an RSMF file strictly according to its rsmf_manifest.json, validated against the published RSMF schema. The Short Message Viewer displays only the content the builder wrote into the manifest—no more and no less.

The rsmf_manifest.json has four root properties: version, participants, conversations, and events. Each event can optionally carry:

• reactions[]—emoji reactions, including value, count, and participant list. See Reaction in the Relativity short message format topic for more information.
• attachments[]—files linked by ID to entries in rsmf.zip.
• edits[]—a sorted history of message edits (newest to oldest).
• Read receipts

All of these properties are optional in the RSMF schema. If an external builder did not emit a property, that property does not render in the Short Message Viewer.

When an external builder omits or misreferences a supported element—such as reactions, attachments, edits, read receipts, or participant lists—that element silently fails to appear in the viewer, or renders as an error, even though Relativity fully supports that element. This is a source-construction gap, not a Relativity viewer or processing defect. Supported elements cannot be inferred, backfilled, or synthesized from other fields; the builder must populate them explicitly in the manifest.

Validating an externally built RSMF file

Validate an externally built RSMF file using the open-source RSMF validator before or immediately after ingestion. The validator checks rsmf_manifest.json against the published RSMF schema and verifies that attachments are correctly cross-referenced between the manifest and rsmf.zip.

The validator and schema are available at https://github.com/relativitydev/rsmf-validator-samples.

See Viewer interface for missing information for more information.

Running the validator

You can run the RSMF validator in two ways:

GUI/CLI application

The repository's bin directory contains a standalone application that accepts an RSMF file as input and returns a validation result. The result is one of the following:

In-Viewer validator

You can also validate a single RSMF file from within the Relativity Short Message Viewer. This method validates the loaded file in place and surfaces the same error and warning categories without requiring a separate tool.

Reading attachment and participant errors

The validator produces two categories of attachment errors:

Participant warnings—for example, X-RSMF-Participants has different members than the JSON participants list—indicate a mismatch between the RSMF file header and the manifest participant list. This condition does not block rendering but can cause unexpected participant display behavior in the Viewer.

Saving an error report

The validator includes a Save Error Report feature that generates a report of all errors and warnings found during validation. Use this report when opening a support case with Relativity.

Important: Error reports may contain personally identifiable information (PII) extracted from the RSMF content. Scrub all PII from the report before sending it to Relativity Support.

Attachment linking requirements

For an attachment to appear in the Short Message Viewer as a family member of its parent message, both of the following conditions must be true:

1. The event entry in rsmf_manifest.json must include an attachments[] array where each entry's id field contains the exact filename—including extension—of the corresponding file in rsmf.zip.
2. The file named by that id must be present in rsmf.zip.

When either condition is not met:

• If the manifest references a file absent from rsmf.zip, the attachment link is broken and the file does not appear in the Viewer.
• If a file is present in rsmf.zip but is not referenced by any event, it is not promoted to a family member. It remains accessible through the rsmf.zip folder but does not render as a linked attachment.

The id value is case-sensitive and must exactly match the filename in the archive. Mismatches in case, path prefix, or extension between the manifest and the archive are a common source of attachment rendering failures in externally built RSMF files.

The following excerpt illustrates correct attachment linking in rsmf_manifest.json:

"events": [
                {
                "id": "msg-001",
                "type": "Message",
                "body": "See the attached document.",
                "participant": "user-a",
                "timestamp": "2024-03-15T10:22:00Z",
                "conversation": "conv-1",
                "attachments": [
                {
                "id": "report_final.pdf",
                "display": "report_final.pdf",
                "size": 204800
                }
                ]
                }
                ]
            

In this example, rsmf.zip must contain a file named exactly report_final.pdf. If the file in the archive is named Report_Final.pdf or report_final.PDF, the link will fail.

Supported elements require explicit manifest population

Relativity supports a rich set of message elements—reactions, edits, read receipts, participant metadata, and custom fields—but can display only elements the builder explicitly wrote into the manifest. Supported elements are not inferred from partial data or derived from source file properties at render time.

For a complete list of supported manifest fields, their behavior by source type, and known limitations, see the RSMF Field Reference. For authoritative field definitions and the full schema, see the published RSMF schema in the validator repository at https://github.com/relativitydev/rsmf-validator-samples.

If a supported element is absent from the manifest of an externally built RSMF, the builder must add it before the RSMF is loaded into Relativity. Missing manifest fields cannot be retroactively populated after ingestion.

Remediation options

When an externally built RSMF fails validation or renders incompletely, you have the following options.

Option 1: Re-route the source data through Relativity's short message conversion

If the source data is a forensic archive—for example, a Cellebrite UFDR file—routing it through Relativity's native short message conversion produces a schema-conformant RSMF. Relativity's conversion pipeline explicitly populates all supported elements for the source type and produces output that passes RSMF schema validation.

This option is available only when you have access to the original source archive. It is not applicable when the source data exists solely as an externally built RSMF with no access to the underlying forensic export.

For supported source types and processing instructions, see the short message conversion overview.

Option 2: Correct and rebuild the RSMF

If re-routing through Relativity's conversion is not possible, correct the RSMF at the source. Use the validator error report to identify specific schema violations and attachment mismatches, then follow these steps:

1. Fix the errors identified by the validator in rsmf_manifest.json.
2. Confirm that every attachment id value in the manifest has an exactly matching filename in rsmf.zip.
3. Add any missing supported elements—reactions, edits, read receipts, participant metadata—to the manifest.
4. Re-validate the corrected RSMF using the GUI/CLI validator before re-ingesting it into Relativity.

Contact the tool vendor—for example, Cellebrite, Oxygen, or ModeOne—or the team that wrote the in-house conversion script for assistance correcting the manifest output.

Relativity Support can help you interpret validator output and identify the specific source of construction gaps in an externally built RSMF. Relativity Support cannot modify the manifest of an externally built RSMF on a customer's behalf.