A schema is a structured definition that specifies how data should be organized, described, and validated within a system. It acts as a model or contract that defines the elements (such as items, attributes, features, and options), their properties, and the rules governing their relationships.
In practice, a schema ensures consistency, standardization, and validation of data, enabling catalogs, configurations, and integrations to work correctly in a unified way. This document will explain how each field works so you can customize your catalog.
Item Model
Items are the fundamental elements of a catalog, representing products, parts, services, or internal building blocks. They include localized names, descriptions, images, and classification data, and can be searched, indexed, and priced. Items may contain geometries (defining their shape), dimensions, attributes, features, options, and sub-items that describe assemblies.
Code (String): Unique, URI-compliant identifier for the item in the source catalog.
RefCodes (Object): Reference codes for integrations. List is expandable. Field values can include formulas. Optional and non-localized.
Names (Object): A flexible set of localized item names. Each name is a short title that may include formulas, such as configurable dimension values.
Description (Object): Extensible set of localized descriptions for this item.
moreInforLinks (Array of objects): Expandable URIs for accessing more item information (non-normalized).
Images (Object)
Classification (Object): Item classification details that standardize the item's nature.
GroupsRefs (Array of objects): List of group codes that this item belongs to.
Visible (Boolean): Sets whether this item is visible by default in content browsing and search. Default: True.
SequenceOrder (Number): Absolute order number in a sequence, with the lowest number first, used in browsing and search results.
Attributes (Array of objects): List of attributes and values for this item, defined at the catalog level and referenced by Attribute Code.
Dimensions (Object): The main dimensions (width, height, depth) define the exact space the item occupies in the design. The item's geometry will match or be resized accordingly (see redimensioning method).
These dimensions are often used in formulas for assembling subitems. Additional dimensions can be added in the "others" field (e.g., Width2, Depth2 for corner cabinets). Units of measure are set at the catalog level.Geometries (Object): Extensible geometric representations of this item; typically includes the "main" geometry. Omit for non-graphical items.
SubItems (Array of objects): Items to be assembled at specific positions and dimensions within this item.
ClearanceDistances (Object): Optional recommended clearance between this item and nearby obstacles.
InsertionOffsets (Object): Recommended offsets can be applied when inserting this item in a design or assembly. These adjust the item's position and orientation based on the insertion context, defined by locationType and installationType. Offsets are given in the item's local coordinate system as a translation vector (position) and rotation (orientation). The position vector measures from the reference location to the item's origin, except for installationType "topAlign," which relates to the item's top. These recommendations are mainly for irregular items or those with special installation needs; standard items typically use the item's origin as the insertion point.
FeatureRefs (Array of objects): Explicit features for this item, with array order determining default UI display order.
RestrictionRefs (Array of strings): List of restrictions limiting available Features and Options for this item, referenced by their "code" with cross-catalog support. Can also apply at the group level.
VariantProposals (Array of objects): List of interesting variations of this item.
EngineeringData (Array of objects): Optional engineering data linked to this item, available on demand based on context. It can also connect to internal or external manufacturing systems.
Extras (String): Add extra info to the item definition for specific app/context use, preferably in JSON format.
Items can be created directly or by referencing others (views), allowing reuse and adaptation for specific catalogs or markets.
Features and Options
Features and options are used to describe what can be changed on an item. They are used to describe an item's configuration possibilites. A feature describes something that can be configured on an item (e.g. a door style, a color, a size, etc.). While an option is a specific value that can be selected for a given feature (e.g. a specific door style, a specific color, a specific size, etc.).
Features define what aspects of an item can be configured (e.g., color, size, style).
Options are the specific values available for a feature (e.g., red, large, modern door style).
Code (String): Unique, URI-compliant identifier for the feature in the source catalog.
Names (Object): A flexible set of localized feature names.
Description (Object): Extensible set of localized descriptions for this feature.
Images (Object)
GroupsRefs (Array of objects): Optional groups to organize similar features within the UI.
SequenceFactor (Integer): Optional number to set display order; defaults to definition order if omitted.
Visible (Boolean): Sets whether this feature is visible by default in content browsing and search. Default: True.
Classification (Object): Item classification details that standardize the features nature.
SelectionType (String): Specifies the main type of option selection this feature supports. The default "singleSelect" allows one choice from a list. "Toggle" means two options for true/false states. For "customNumeric" features, only the first attribute in itemModification sets the numeric value.
Condition (String): Optional a boolean expression to control whether this feature is applicable or not.
SequenceOrder (Number): Absolute order number in a sequence, with the lowest number first, used in browsing and search results.
DefaultOptionCode (String): The system's default option. If undefined, the first option is used. For cross-catalog features, this can reference an item from another catalog (see catalogDependencies in the catalog model).
Options (Array of objects): List of selectable options. The array order can set the default display order in the UI.
Material Model
A "material" defines rendering properties and differs from coverings like paint or fabric, which users browse in catalogs. Coverings link to internal material definitions. Materials tie to an item's geometry layer to set its appearance. Unlike static materials, explicit materials can be reused and updated dynamically via formulas and Features & Options.
Code (String): Unique, URI-compliant identifier for the material in the source catalog.
Names (Object): A flexible set of localized material names.
Description (Object): Extensible set of localized descriptions for the material.
GroupsRefs (Array of objects): Optional groups to organize similar material within the UI.
mCode (String): Normalized "material code" describes key material appearance traits. The mCode taxonomy is rendering engine agnostic, allowing any engine to use it to set material properties based on its capabilities. For example, in Physically-based Rendering, it controls parameters like roughness, metallic factor, and emissive factor.
BaseColorFactor (Array of numbers): Base color (RGB) with optional alpha for the material.
Color accuracy: Material color depends on base color, other properties, lighting, and environment.
Colorspace: If a baseColor texture map exists, baseColorFactor acts as a linear multiplier. Without a texture map, values are in sRGB colorspace. Different viewers expect sRGB or linear RGB; the Content Platform APIs allow runtime colorspace conversion.
Alpha channel: The optional alpha (A in RGBA) indicates material presence: 0 means no material, 1 means full presence. Default is 1.0 if unspecified, recommended for real-world materials.Textures (Object): Optional data defining material property variations across a geometry's surface (UV space).
Advanced (Object): Overrides values normally set by mCodes. Not recommended for most cases. Report any mCode issues.
Extras (String): Additional info can be added to the material definition for specific applications or contexts, preferably in JSON format.
Restriction Model
Restrictions are used to limit the available options for a given feature in the context of a specific item in a given configuration state.
Code (String): Unique, URI-compliant identifier for the restriction in the source catalog.
Names (Object): A flexible set of localized restriction names.
Condition (String): Optional condition that can be used to invalidate this restriction at run-time.
ExcludedCombinations (Array of objects): Set of invalid option combinations; all others are valid.
Attribute Model
Attributes describe an item's internal properties and state. They are used in formulas to control behaviors like parametric assembly, dynamic materials, and item configuration logic. Attributes with reference codes (refCodes) can represent item states and serve as inputs for pricing calculations.
Code (String): Unique, URI-compliant identifier for the attribute in the source catalog.
RefCodes (Object): Attribute code used as a reference for external integrations (e.g., pricing). Non-localized. Values may include formulas.
Names (Object): Optional localized name of this attribute (useful in authoring or troubleshooting contexts).
Description (Object): Extensible set of localized descriptions for the attribute.
moreInforLinks (Array of objects): Extensible set of additional URIs to access more information regarding the item (non-normalized).
Images (Object)
DataType (String): Data type of the value of the attribute.
DefaultValue (String): Sets the default value for the attribute. If omitted, the default is
undefined. For "map" data types, use a JSON string of key-value pairs, like'{"small":20,"medium":60,"large":100}'. For arrays, use a JSON string like'["small","medium","large"]'.GroupRefs (Array of Strings): Optional groups for organizing similar attributes in the UI.
Visible (Boolean): Sets whether this item is visible by default in content browsing and search. Default: False.
Overridable (Boolean): Indicates if the attribute value can be overridden by a parent catalog through catalog dependencies. Default: True.