26.07 Storage Module

The Storage module is used to indicate the storage for artifacts. The Storage module introduces a new type Storage defined as

type Storage = Artifact[]

where all Artifact type objects in it MUST have an id member in their metadata and the id values MUST be unique.

interface Metadata {
	id: string // REQUIRED if Storage module is in use
	// ...
}

The id MUST be used to resolve the Artifact in Form to the Artifact in Storage, i.e., they are considered the same object. If two or more Artifact objects share the same id, the Artifact appearing first in the array MUST be considered the only Artifact with that id and the rest MUST be discarded.

The Storage module also introduces new members in FormProperties, defined as

interface FormProperties {
	storage: "path" | "impl" // OPTIONAL
	storagePath: string // OPTIONAL
	storageOverwrite: boolean // OPTIONAL
	storageEnforce: boolean // OPTIONAL
	// ...
}

where

• storage is OPTIONAL and its value MUST be one of those specified above. When it is provided, the Storage module is in use. When its value is "impl", the implementation MUST specify the Storage and use it to resolve the scene with the Form object.
• storagePath is OPTIONAL and its value MUST be of type string and MUST be a path or URL to a JSON file of the Storage data used for the Form. If it is not provided, the default value "./storage.json" MUST be used. Its value MUST be ignored if storage has a value other than "path".
• storageOverwrite is OPTIONAL and its value MUST be of type boolean. If it is not provided, the default value true MUST be used. Its value MUST be ignored if storage is not specified. When it is true, any conflict between an Artifact in Form and an Artifact in Storage MUST be resolved in favor of the Artifact in Storage; when it is false, the Artifact in Form MUST be merged into the corresponding Artifact in Storage member by member at every level, where each member present in Form overwrites the corresponding member in Storage, and the merged Artifact MUST be used, providing further customization of the scene in addition to the Storage data.
• storageEnforce is OPTIONAL and its value MUST be of type boolean. If it is not provided, the default value true MUST be used. Its value MUST be ignored if storage is not specified. When it is true, any Artifact in Form that is not present in Storage MUST be discarded.

When a storage value is provided, it is valid, though not recommended, to have an Artifact in Form containing only metadatawith an id, and use storageOverwrite to resolve it to the corresponding Artifact in Storage. Storage MUST contain the full information of the artifacts. If Storage is not provided or the relevant Artifact is missing from Storage, an Artifact missing a content or type member MUST be discarded.