SchemaFactoryObjectOptions Interface
Options when declaring an object node's schema
To use, import via fluid-framework/alpha.
For more information about our API support guarantees, see here.
Signature
export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown> extends NodeSchemaOptionsAlpha<TCustomMetadata>
Extends: NodeSchemaOptionsAlpha<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.
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.
The existing import and export APIs have similar problems. For example currently the exportVerbose API with stored keys preserves unknown optional fields, but Unhydrated nodes produced by TreeNode constructors, insertable content, and importVerbose do not. clone(node) however can be used to clone a node preserving unknown optional fields.
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.