solai-data-modeler

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 }
  },
  "required": ["name"]
}

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

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