Author your own object schema, or reuse a published schema from an open URL.
A schema is the object vocabulary for a model. It defines which object type values exist, which subtypes (as base:subtype in type) are allowed, which property fields objects can carry, and how objects look on the diagram. IOModel ships built-in schemas, but you can also author your own or reuse one from a URL.
Three ways to use a schema
Set objects_schema on the model root to one of: 1. a built-in id (c4,
kubernetes), 2. your own custom schema, or 3. a URL to a schema published at
an open address.
# models/my-product.yaml
objects_schema: c4 # built-in
# objects_schema: my-schema # custom
# objects_schema: https://example.com/my-schema.yaml # reuse from a URLWhat a schema controls
| Schema part | Controls |
|---|---|
object_types | Allowed type values on objects |
object_subtypes | Allowed subtype values (written as base:subtype in object type) |
properties | Fields objects can carry (e.g. status, tech) |
view_features | Diagram figure and default icon |
| Vocabularies | Suggested values for properties |
Schema file anatomy
A schema is a YAML file with top-level metadata, shared properties, object types, and subtypes:
base: objects-base:1.0.0
name: my-schema
title: My Schema
description: Object vocabulary for my domain.
version: 1.0.0
# Fallback diagram icon when an object has no custom icon
default_icon: system.svg
# Reusable property set (YAML anchor) referenced by object types
x-default-properties: &default_properties
- name: owner
type: string
description: Team that owns the object.
- name: status
type: enum
description: Lifecycle status.
enum_values:
- name: active
description: In use.
icon: lucide:check-circle
- name: deprecated
description: Being retired.
icon: lucide:trash-2
- name: tech
type: array
description: Technologies used.
items:
type: string
description: A technology value.
search_values: technology_vocabulary:1.0.0
object_types:
- name: service
description: A deployable unit that exposes an API.
properties: *default_properties
view_features:
figure: box
default_icon: container.svg
available_subtypes:
- name: database
- name: broker
- name: actor
description: A human or external system.
properties: *default_properties
view_features:
figure: actor
actor_picture: person.svg
default_icon: person.svg
object_subtypes:
- name: database
description: A data store.
view_features:
figure: db
default_icon: database.svg
- name: broker
description: A message broker or queue.
view_features:
figure: queue
default_icon: broker.svgTop-level fields
| Field | Purpose |
|---|---|
base | Base schema reference (e.g. objects-base:1.0.0) |
name | Schema id |
title, description, version | Metadata |
default_icon | Fallback diagram icon for objects without one |
Object types and subtypes
| Field | On | Purpose |
|---|---|---|
name | type / subtype | Subtype name in schema; written in YAML as base:name in type |
description | type / subtype | Explanation |
properties | type | Property definitions (often a shared anchor) |
view_features | type / subtype | Diagram figure and icon |
available_subtypes | type | Which subtypes this type allows |
available_subtypes is also accepted as avaliable_subtypes (a tolerated
legacy spelling). Prefer available_subtypes in new schemas.
Property definitions
Each property declares a name, a type, and an optional description.
- name: owner
type: string
description: Team that owns the object.| Property field | Purpose |
|---|---|
type | string, array, enum, or a custom value type |
items | Element definition when type: array |
enum_values | Allowed values (name, description, icon) for type: enum |
search_values | Vocabulary reference for suggested values |
View features
view_features control how an object renders on the diagram:
| Field | Purpose |
|---|---|
figure | Node shape: box, actor, db, or queue |
default_icon | Icon file used when the object has no custom icon |
actor_picture | Figure image for figure: actor |
Icons referenced here are resolved as schema assets for the diagram.
Vocabularies
Vocabularies provide suggested values for properties (via search_values). A vocabulary file is a list of values with an optional hierarchical category:
# technology_vocabulary
values:
- name: postgresql
category: database:relational
description: Advanced open-source relational database.
- name: kafka
category: messaging:streaming
description: Distributed event streaming platform.A property references a vocabulary as name:version, for example technology_vocabulary:1.0.0.
How objects use the schema
Pick a type
An object’s type must be one of the schema’s object_types.
Optionally set a subtype
A subtype in object type (e.g. container:database) maps to an object_subtypes entry for visuals and semantics.
Fill properties
Schema-defined properties (like status, tech) appear as fields on the object.
Create your own schema
Start from base
Reference objects-base:1.0.0 and give your schema a name, title, and version.
Define shared properties
Declare a reusable property set with a YAML anchor.
Add object types
List your object_types, attach properties, and set view_features.
Add subtypes
Model the smallest vocabulary that fits your domain. A focused schema with a handful of types is easier to apply consistently than a large one that tries to cover everything.
Related
For model and object YAML syntax, see the YAML Model Reference. For deployment-oriented modeling, see Environments and Deployment.
Last updated on