Data track schema metadata by ladvoc · Pull Request #1994 · livekit/client-sdk-js

ladvoc · 2026-07-01T18:57:24Z

Adds support for attaching schema metadata to data tracks mirroring the implementation in livekit/rust-sdks#1159.

Usage:

// Publish
const track = await room.localParticipant.publishDataTrack({
  name: 'my_sensor_data',
  schema: { name: 'rgb', encoding: 'protobuf' },
  frameEncoding: 'protobuf',
});

// Subscribe
room.on(RoomEvent.DataTrackPublished, (track) => {
  console.log(track.info.schema);         // { name: 'rgb', encoding: 'protobuf' }
  console.log(track.info.frameEncoding);  // 'protobuf'
});

Note: the scope of this PR has been limited to exposing schema metadata fields; schema storage will be added in a follow-up.

Areas for reviewers to scrutinize:

Convention for Protobuf conversion
API shape of DataTrackSchemaId

changeset-bot · 2026-07-01T18:57:29Z

⚠️ No Changeset found

Latest commit: 8c5df6a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-07-01T18:59:36Z

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	101.66 KB (+0.92% 🔺)
dist/livekit-client.umd.js	110.56 KB (+0.78% 🔺)

1egoman

Generally looks good to me!

1egoman · 2026-07-02T15:22:53Z

+
+export const DataTrackSchemaEncoding = {
+  from(protocol: ProtocolDataTrackSchemaEncoding): DataTrackSchemaEncoding {
+    switch (protocol.value.case) {
+      case 'wellKnown':


thought: I'm a big fan of this pattern where you have a type and value which share the same name, and typescript merges them into one identifier which can be used in either context. However, @lukasIO has raised in the past this can be somewhat confusing if you don't understand what is going on.

I'll let him weigh in but I'm fine with this as is especially since it's not directly part of the external interface.

1egoman · 2026-07-02T15:24:43Z

+/**
+ * Identifier for a data track schema.
+ *
+ * A compound identifier with two components: {@link name} and {@link encoding}.
+ *
+ * Two IDs are equal only if both components match; the same name with a different
+ * encoding refers to a distinct schema.
+ */
+export type DataTrackSchemaId = {
+  /** Name component of the identifier. Must be non-empty and no longer than 256 characters. */
+  name: string;
+  /** Encoding component of the identifier. */
+  encoding: DataTrackSchemaEncoding;
+};


thought: It is weird to me to have a type which ends in -Id that is a non primative type. Should this be called something maybe like DataTrackSchemaReference or even just DataTrackSchema?

Open to changing this, but my thinking here was this acts like a compound ID or key in a database:

When publishing a track, you provide the ID of the schema it uses, not the schema itself.

When storing/retrieving the definition for the schema, it is referenced by this ID.

Maybe DataTrackSchemaKey would make more sense here since this isn't a primitive? Also worth noting, not that we necessarily need to align with it, but it is called -Id at the protocol level.

1egoman · 2026-07-02T15:33:08Z

+const WELL_KNOWN_TO_SCHEMA_ENCODING: Partial<
+  Record<ProtocolWellKnownSchemaEncoding, DataTrackSchemaEncoding>
+> = {
+  [ProtocolWellKnownSchemaEncoding.PROTOBUF]: 'protobuf',
+  [ProtocolWellKnownSchemaEncoding.FLATBUFFER]: 'flatbuffer',
+  [ProtocolWellKnownSchemaEncoding.ROS1_MSG]: 'ros1Msg',
+  [ProtocolWellKnownSchemaEncoding.ROS2_MSG]: 'ros2Msg',
+  [ProtocolWellKnownSchemaEncoding.ROS2_IDL]: 'ros2Idl',
+  [ProtocolWellKnownSchemaEncoding.OMG_IDL]: 'omgIdl',
+  [ProtocolWellKnownSchemaEncoding.JSON_SCHEMA]: 'jsonSchema',
+};


nitpick: I'm assuming this always is a 1:1 mapping? If so, you (I'll leave it up to you to decide) could avoid the duplication with something like:

Suggested change

const WELL_KNOWN_TO_SCHEMA_ENCODING: Partial<

Record<ProtocolWellKnownSchemaEncoding, DataTrackSchemaEncoding>

> = {

[ProtocolWellKnownSchemaEncoding.PROTOBUF]: 'protobuf',

[ProtocolWellKnownSchemaEncoding.FLATBUFFER]: 'flatbuffer',

[ProtocolWellKnownSchemaEncoding.ROS1_MSG]: 'ros1Msg',

[ProtocolWellKnownSchemaEncoding.ROS2_MSG]: 'ros2Msg',

[ProtocolWellKnownSchemaEncoding.ROS2_IDL]: 'ros2Idl',

[ProtocolWellKnownSchemaEncoding.OMG_IDL]: 'omgIdl',

[ProtocolWellKnownSchemaEncoding.JSON_SCHEMA]: 'jsonSchema',

};

const WELL_KNOWN_TO_SCHEMA_ENCODING = Object.fromEntries(

Object.entries(SCHEMA_ENCODING_TO_WELL_KNOWN)

.map(([key, value]) => [value, key])

) as Record<ProtocolWellKnownSchemaEncoding, string>;

I had to add a Partial to get the types to work. However, I am still getting this error in CI:

error TS2550: Property 'fromEntries' does not exist on type 'ObjectConstructor'.

Probably missing something obvious.

1egoman · 2026-07-02T15:48:02Z

 /** Options for publishing a data track. */
 export type DataTrackOptions = {
  name: string;
+
+  /** Schema describing frames sent on the track. */
+  schema?: DataTrackSchemaId;
+
+  /** Encoding of frames sent on the track. */
+  frameEncoding?: DataTrackFrameEncoding;
 };


thought: To confirm - is there a relationship between schema encoding and frame encoding? Or can a user specify any type of frame encoding for any time of schema encoding?

If there is a relationship and there are some combinations that aren't allowed, I think it would be good at least in the public type (DataTrackOptions) to make sure these non allowed combinations will cause a type error. A way you could accomplish this could be add some generics to DataTrackOptions (with defaults so it is backwards compatible) and use those to key into WELL_KNOWN_TO_SCHEMA_ENCODING / WELL_KNOWN_TO_FRAME_ENCODING (or a similar type of structure which represents the allowed combinations) within the type.

Great callout! Yes, the valid combinations are documented in the doc comments for the enum, however, I would like to have some validation of this. I'm not sure if it is feasible to make this validated at the type level (at least not in all client SDKs), but we could at least validate at publish time. Another option is to implement this on the SFU side and have it return an error during track publication if an invalid combination is used (possible advantage: no need to update this logic in every client if new schema/frame encoding cases are added in the future). What are your thoughts here?

I'm not sure if it is feasible to make this validated at the type level (at least not in all client SDKs)

It's probably not something that would need to be done in all client sdks, but if this isn't something that is likely to change and in the future new relationships will be purely additive (ie, a -> b will always be invalid, but a -> (a newly introduced) c may be no longer added in the future) then I think at least in a web context, it would be typical for typescript to assert this. So IMO if it's not too hard it's worth doing.

Definitely though implement this as a "denylist" and not an "allowlist" so that future newly introduced combos will work in old sdks.

Another option is to implement this on the SFU side and have it return an error during track publication if an invalid combination is used

IMO it's worth doing this in both places, just like you'd have both client side and server side form validation.

1egoman · 2026-07-02T15:49:45Z

Longer term, I want to discuss how to get this using the Serializer type but I think that can wait until schema related serialization / deserialization is being done in other sdks. And I don't think the migration path to that would be too crazy.

Co-authored-by: Ryan Gaus <ryan.gaus@livekit.io>

ladvoc added 3 commits July 1, 2026 11:12

Update protocol

999be68

Schema metadata support

09a1473

Testing

868b284

Format

04eaa80

1egoman approved these changes Jul 2, 2026

View reviewed changes

ladvoc and others added 3 commits July 2, 2026 09:22

Use toStrictEqual for tests

6bfa1d9

Simplify enum mapping

ddc00b9

Don't use wildcard export

8c5df6a

Co-authored-by: Ryan Gaus <ryan.gaus@livekit.io>

Uh oh!

Conversation

ladvoc commented Jul 1, 2026

Uh oh!

changeset-bot Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented Jul 1, 2026

size-limit report 📦

Uh oh!

1egoman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1egoman commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading