SchemaFactoryObjectOptions Interface

Options when declaring an object node's schema

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Signature

export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown> extends NodeSchemaOptions<TCustomMetadata>

Extends: NodeSchemaOptions<TCustomMetadata>

Type Parameters

Parameter	Default	Description
TCustomMetadata	unknown

Properties

Property	Alerts	Modifiers	Default Value	Type	Description
allowUnknownOptionalFields	Alpha	optional	false	boolean	Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration. Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client that has upgraded the document's schema to include those optional fields.

Property Details

allowUnknownOptionalFields

Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration. Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client that has upgraded the document's schema to include those optional fields.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

allowUnknownOptionalFields?: boolean;

Type: boolean

Remarks

The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly upgrade documents to include schema for new optional features.

However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between code and documents. When opening such documents, the API presented is still determined by the view schema. This can have implications on the behavior of edits or code which uses portions of the view schema, since this may inadvertently drop data which is present in those optional fields in the document schema.

Consider the following example:

const sf = new SchemaFactory("com.example");
class PersonView extends sf.object("Person", { name: sf.string }, { allowUnknownOptionalFields: true }) {}
class PersonStored extends sf.object("Person", { name: sf.string, nickname: sf.optional(sf.string) }) {}
// Say we have a document which uses `PersonStored` in its schema, and application code constructs
// a tree view using `PersonView`. If the application for some reason had implemented a function like this:
function clonePerson(a: PersonView): PersonView {
	return new PersonView({ name: a.name });
}
// ...or even like this:
function clonePerson(a: PersonView): PersonView {
 return new PersonView({ ...a})
}
// Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.

If an application wants to be particularly careful to preserve all data on a node when editing it, it can use import/export APIs with persistent keys.

Note that public API methods which operate on entire nodes (such as moveTo, moveToEnd, etc. on arrays) do not encounter this problem as SharedTree's implementation stores the entire node in its lower layers. It's only when application code reaches into a node (either by accessing its fields, spreading it, or some other means) that this problem arises.