Define Content Types for CMS SaaS

Why content type definition differs on SaaS

On CMS PaaS, content types live inside your .NET application. You define a C# class, deploy the application, and CMS discovers the type at startup. The type definition and the rendering code ship together in the same deployment.

CMS SaaS separates these concerns. Content types are defined and pushed to the cloud independently of your frontend application. Your frontend queries content through Graph and renders it however it chooses. This separation means the content model can evolve without redeploying your frontend — and your frontend can change without touching the content model.

The tradeoff: you lose the convenience of a single .NET project that contains everything. You gain a cleaner architecture where content modeling, content delivery, and content rendering are independent layers.

What you will do

1. Define a content type using the SaaS content type schema
2. Configure properties with validation and editor hints
3. Deploy the type to your CMS SaaS environment using the CLI
4. Verify the type in the CMS editor and Visual Builder

How SaaS content types differ from PaaS

Aspect	CMS PaaS	CMS SaaS
Definition format	C# classes with attributes	JSON/YAML manifest files or the management API
Deployment	Built into the .NET application	Pushed via CLI or API, independent of frontend
Discovery	CMS scans assemblies at startup	CMS receives type definitions from the cloud pipeline
Property types	.NET types (string, XhtmlString, ContentReference)	Platform-defined types (Text, RichText, ContentReference)
Visual Builder support	Not available	Types define canvas behavior — sections, allowed components
Rendering	Razor views, MVC controllers	External frontend via Graph (React, Next.js, etc.)

Define a content type

Content types for CMS SaaS are defined in manifest files that describe the type’s properties, validation rules, and editor configuration.

Content type manifest

JSON manifest

json Copy

{
  "key": "HeroBlock",
  "displayName": "Hero Banner",
  "description": "A full-width hero section with heading, body text, image, and call-to-action",
  "baseType": "Component",
  "sortOrder": 100,
  "features": {
    "localization": {
      "enabled": true
    }
  },
  "properties": {
    "heading": {
      "type": "Text",
      "displayName": "Heading",
      "required": true,
      "sortOrder": 10,
      "editorSettings": {
        "maxLength": 120
      }
    },
    "bodyText": {
      "type": "RichText",
      "displayName": "Body Text",
      "sortOrder": 20
    },
    "backgroundImage": {
      "type": "ContentReference",
      "displayName": "Background Image",
      "allowedTypes": ["Image"],
      "sortOrder": 30
    },
    "ctaText": {
      "type": "Text",
      "displayName": "Button Text",
      "sortOrder": 40,
      "editorSettings": {
        "maxLength": 50
      }
    },
    "ctaLink": {
      "type": "Url",
      "displayName": "Button Link",
      "sortOrder": 50
    }
  }
}

Key fields:

• key — The unique identifier for this type. Use PascalCase. This value is permanent once deployed — changing it creates a new type rather than renaming the existing one.
• baseType — Determines how the type behaves. Page for standalone pages with URLs. Component for blocks used within Visual Builder. Media for uploadable assets.
• properties — Each property has a platform-defined type. Common types: Text, RichText, ContentReference, Url, Boolean, Number, DateTime.
• features.localization — When enabled, property values can differ per language.

Define a page type with layout sections

Page types that support Visual Builder need layout section definitions. Sections define the grid structure that authors see on the canvas.

Page type with Visual Builder sections

JSON manifest

json Copy

{
  "key": "LandingPage",
  "displayName": "Landing Page",
  "baseType": "Page",
  "properties": {
    "metaTitle": {
      "type": "Text",
      "displayName": "Meta Title",
      "sortOrder": 10,
      "group": "SEO"
    },
    "metaDescription": {
      "type": "Text",
      "displayName": "Meta Description",
      "sortOrder": 20,
      "group": "SEO"
    }
  },
  "visualBuilder": {
    "sections": [
      {
        "key": "headerSection",
        "displayName": "Header",
        "columns": 1,
        "allowedTypes": ["HeroBlock", "NavigationBlock"]
      },
      {
        "key": "mainContent",
        "displayName": "Main Content",
        "columns": 2,
        "allowedTypes": ["TextBlock", "ImageBlock", "CardBlock", "FormBlock"]
      },
      {
        "key": "footerSection",
        "displayName": "Footer",
        "columns": 1,
        "allowedTypes": ["FooterBlock", "NewsletterSignupBlock"]
      }
    ]
  }
}

Section configuration:

• columns — Number of columns in the grid (1 for full-width, 2 for side-by-side, etc.)
• allowedTypes — Restricts which component types can be dropped into the section. Omit this field to allow all components.

Deploy types to CMS SaaS

Content types deploy through the Optimizely CLI. The CLI reads your manifest files and pushes the definitions to the cloud.

Deploy content types

CLI

bash Copy

# Authenticate with your CMS SaaS environment
optimizely login --environment production

# Validate manifests before deployment
optimizely content-types validate ./content-types/

# Deploy content types to the target environment
optimizely content-types push ./content-types/ --environment development

# Verify deployed types
optimizely content-types list --environment development

Deployment workflow:

1. Validate locally — content-types validate checks your manifests for syntax errors, missing required fields, and type conflicts before anything reaches the cloud.
2. Deploy to development — Push to your development environment first. Create test content and verify the types work in Visual Builder.
3. Promote to staging — Once validated, push the same manifests to staging for integration testing.
4. Promote to production — After staging verification, push to production.

CMS

Content type deployments are additive by default. Pushing a modified type updates the existing definition. Removing a property from the manifest does not delete existing content — the property becomes hidden in the editor but data is preserved for safety.

Verify in the editor

After deployment:

1. Open the CMS editor in the target environment
2. Create a new page using your page type
3. Verify that Visual Builder opens with the sections you defined
4. Add components to each section and confirm that allowedTypes restrictions work
5. Fill in property values and verify validation rules (required fields, max length)

Property types reference

SaaS type	PaaS equivalent	Description
Text	string	Single-line or multi-line plain text
RichText	XhtmlString	HTML content with formatting toolbar
ContentReference	ContentReference	Link to another content item
Url	Url	External or internal URL
Boolean	bool	True/false toggle
Number	int / double	Numeric value
DateTime	DateTime	Date and optional time
ContentArea	ContentArea	Ordered list of content references (Visual Builder sections)

Common issues

Issue	Cause	Fix
Type not visible after deployment	Deployment targeted wrong environment	Run content-types list to verify the target environment
Property missing in editor	Property key typo in manifest	Compare manifest keys against the deployed type definition
Validation error on push	Invalid property type or missing required field	Run content-types validate and fix reported errors
Visual Builder sections missing	Page type lacks visualBuilder.sections	Add the visualBuilder configuration to the page type manifest

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Content Modeling in Optimizely
• CMS SaaS vs CMS PaaS

🔧Follow a guide

• Create a Content Type (PaaS)
• Visual Builder Basics
• Deploy to CMS SaaS