solai-data-modeler

name	solai-data-modeler
description	Design and validate Contextual.io Object Type schemas. Use when creating new object types, adding properties, defining relations, or reviewing schema correctness. Do NOT use for flow changes — use solai-flow-editor for those.

SolAI Data Modeler

Use this skill to design, validate, and deploy Object Type schemas on the Contextual.io platform.

Schema rules (non-negotiable)

Structure

• All schemas must have a top-level primaryKey property whose value is the name of the primary key field
• ALL schemas must have at least one non-generated required property (e.g. name)
• Do NOT mark auto-generated fields (UUIDs, timestamps) as required — they don't exist at validation time
• Do not use JS-style comments (//) — use description properties or $comment instead
• All object type IDs must use only lowercase letters, numbers, and dashes — suggest a corrected alternative if the user requests otherwise
• Only generate valid schemas — if asked to produce something invalid, decline politely and explain why

Primary keys

• Unless told otherwise, ALL new schemas use an auto-generated UUID for the primary key:

  "id": { "type": "string", "generate": { "type": "uuid", "format": "v4" } }
  

• Auto-generated primary keys must NOT appear in the required array
• You CANNOT propose changes to a primary key for an object type that already exists or has been saved — only the default (unsaved) schema may have its primaryKey changed

Default schema baseline

When starting from scratch:

{
  "primaryKey": "id",
  "type": "object",
  "$comment": "Purpose of this object type",
  "properties": {
    "id": { "type": "string", "generate": { "type": "uuid", "format": "short" } },
    "name": { "type": "string", "minLength": 1 },
    "description": { "type": "string", "minLength": 1 }
  
   

Platform-provided _metaData (do not replicate in schema)

Every record automatically receives a _metaData envelope from the platform — it is never part of the schema definition:

"_metaData": {
  "createdAt": "...",
  "updatedAt": "...",
  "hash": "...",
  "id": "...",
  "schema": "native-object:<type-id>",
  "type": "custom",
  "version": 1,
  "secrets": []
}

Never add createdAt, updatedAt, hash, version, or secrets to a schema — they are already present on every record via _metaData. Reference them in flow logic as msg.payload._metaData.createdAt etc.

Schema-defined auto-generated fields

Only add these when you need a generated value inside the record body itself (separate from _metaData), for example a secondary timestamp or a display-facing date:

"publishedAt": { "type": "string", "generate": { "type": "date-time" } }

Do not mark these as required.

Relations

• The relations section is ALWAYS a top-level schema property — never nested inside a property definition
• Relations are defined on the CHILD object pointing TO the parent — never on the parent
• typeRef must ONLY reference the primaryKey path of the parent: "native-object:<type-id>/<primaryKey>"
• Do not allow typeRef to be set to anything other than the parent's primaryKey
• Example:

  "relations": {
    "customer": {
      "typeRef": "native-object:customer/id",
      "localField": "customerId",
      "displayField": "name"
    }
  }
  

Secret fields

• Designate sensitive string properties with "secret": true to encrypt and store in the key store
• Example:

  "apiKey": { "type": "string", "description": "Encrypted API credential", "secret": true }
  

Not supported

• Contextual does not support indexed/index fields — if a user asks about indexing, decline to add it and suggest they contact Contextual if indexing is a needed feature

Internal native-object types only

• The schema you design is the inner schema body of an internal native-object type. At deploy time the /solai-cli skill wraps it in the type-registration envelope, which always sets "type": "custom" and "objectType": "internal".
• Do not design for, or set, "objectType": "external". External types are a specialized Tenant-API construct with no normal flow / CLI / Native Object node CRUD and no schema-authoring path here. Every type designed with this skill is "internal".
• Hand off the inner schema and let /solai-cli author the envelope — do not assemble the envelope here. See solai-cli/cli-reference.md → Object Type Schemas for the envelope shape.

Documentation references

Use the solai-knowledge skill to verify platform behaviour before proposing anything uncertain. Prefer these specific doc paths:

Topic	Doc path
Schema structure and JSON Schema features	components-and-data/object-types/object-type-details/data-schema/README.md
UUID generation formats and options	components-and-data/object-types/object-type-details/data-schema/generated-properties/uuids.md
Auto-generated date/time fields	components-and-data/object-types/object-type-details/data-schema/generated-properties/dates-and-times.md
primaryKey immutability rules	components-and-data/object-types/object-type-details/data-schema/id-and-primarykey-permanence.md
Secret fields	components-and-data/object-types/object-type-details/data-schema/secret.md
Validation patterns (enums, booleans, etc.)	components-and-data/object-types/object-type-details/data-schema/frequently-used-validation.md
Object type definition and relations	components-and-data/object-types/object-type-details/definition.md
Worked schema examples	components-and-data/object-types/examples.md

Workflow

1. Before proposing a schema, check if the object type already exists using ctxl types get --type <type-id> — this determines whether primaryKey changes are allowed
2. For any schema feature you are uncertain about, look it up in the docs above before proposing
3. Present the full proposed JSON schema for user review before any deployment
4. Once the user approves, hand off to the /solai-cli skill for deployment — do not attempt to run ctxl commands directly via Bash. Doing so skips the skill's schema format reference and auth recovery, causing flag errors and wasted tokens.
5. After creation, confirm with ctxl types get --type <type-id> to verify the deployed schema matches intent
6. When designing related types, present all schemas together so relations can be reviewed as a set before any are deployed