Data modeling with Shapes

• A Shape is made up of components, the most atomic fields in Crystallize (text, numbers, media, relations, etc.).
• Components can be organized using structural components like Chunk, Choice, or Multiple Choice, giving you repeatability and polymorphic flexibility.
• Shapes can also embed Pieces, which are reusable sets of fields. Pieces allow you to avoid duplication and apply the same structured content model in multiple Shapes.

When an editor creates a product, folder, or document in the catalogue, the fields that appear are determined by the Shape chosen.

Crystallize provides three core shape types:

• Product Shape
  Used to model products, including variants, pricing, stock, and attributes.
  Example: A "Sneaker" shape with fields for size, color, material, and product images.
• Document Shape
  Used for editorial or marketing content.
  Example: A "Blog Post" , “Landing page” or a simple “About us page” shape with fields for headline, rich text body, featured image, and author.
• Folder Shape
  Used to organize the catalogue and group related items. Folder shapes can be created in a hierarchy and make up the main structure of your product universe.
  Example: A "Category" shape to group all “Shoes” products, or a "Campaign" folder for seasonal collections.

• Consistency: All products or documents created with a Shape follow the same structure, making your data reliable.
• Flexibility: Structural components let you model polymorphic or complex products (like a guitar vs an amplifier in the same Shape).
• Reusability: With Pieces and repeatable components, you can build once and apply across many use cases.
• Scalability: Whether you’re managing 100 products or 1 million, Shapes provide a predictable data structure that scales with your business.

To define a new Shape in Crystallize:

1. Navigate to Shapes
   Go to Settings → Shapes in the left-hand menu. Here you can view all existing Shapes grouped under Product Shapes, Folder Shapes, and Document Shapes.
2. Add a New Shape
   Click the + icon at the top to create a new Shape. Choose whether it should be a Product, Folder, or Document Shape depending on your use case.
3. Drag and Drop Components
   From the right-hand panel, drag the desired components (e.g. Single Line, Numeric, Images) into your Shape. Arrange them in the order you want editors to fill them in.
4. Configure Component Settings
5. • Name: Give each component a clear name, such as “Headline,” “Weight,” or “Specifications.”
   • Identifiers: Each field automatically gets a unique identifier (used in APIs), which can be customized.
   • Localization: Enable localization if you want the field to support multiple languages.
   • Discoverability: Choose whether a field should be included in the Discovery API.
   • Repeatable: For components inside Chunks, you can allow repeatability (e.g. a list of ingredients or specifications).
6. Use Structural Components
7. • Add Chunks to group related fields into repeatable sets (e.g. Weight + Length under Specifications).
   • Use Choice or Multiple Choice if your Shape needs polymorphism (e.g. a Guitar could include either Electric Specs or Acoustic Specs).
8. Embed Pieces
   You can drag Pieces into a Shape to reuse predefined sets of fields like SEO metadata, banners, or product visualizers.
9. Save Your Shape
   Once configured, click Update (or Save) to store your new Shape. It will now be available when creating items in the catalogue.

Pieces in Crystallize are reusable sets of fields that can be embedded inside Shapes. They are ideal for modeling content that you want to reuse across products, documents, or folders - for example SEO data, environmental impact information, or marketing banners.

Steps to Create a Piece

1. Navigate to Pieces
   Go to Settings → Shapes and scroll down to the Pieces section.
2. Add a New Piece
   Click the + icon to create a new Piece. Give it a clear name that describes its purpose (e.g. “SEO Metadata,” “Environmental Impact Data,” “Banner”).
3. Add Components
   From the right-hand panel, drag and drop the components you need.
4. • Add simple fields like Single Line or Numeric.
   • Add structured content like Chunks for repeatable values.
   • Use relations (Item Relation, Grid Relation) if the piece needs to connect to other catalogue items.
5. Configure Each Component
6. • Name & Identifier: Provide a descriptive name (e.g. “Carbon footprint”) and check the identifier if you want to adjust it for API usage.
   • Localization: Enable localization if the content needs to be translated into multiple languages.
   • Repeatable: For components inside Chunks, enable repeatability when you want multiple entries (e.g. list of sustainability metrics).
7. Save the Piece
   Once configured, click Update to save your Piece. It is now available to be embedded into any Shape.