Skip to content
View as Markdown

Entity Classification

Every domain class of the CDM specialises one of a few abstract base classes defined in the core subset. The choice decides whether instances have a platform-wide identity (a GRID), which core relations the class can take part in — their domains and ranges are stated in terms of these base classes — and how the class relates to external ontologies. The base set is deliberately minimal; bounded contexts refine it with their own classes and mixins.

Base classes

Base classes and mixins of the core schema. Core mixins are attached with instantiates; domain mixins use mixins:. Neither uses is_a.

Any
core_Entity  [instantiates: core_WithGRID, core_WithMaturity, core_WithPlatformAPI]
  core_Activity
  core_Artifact
core_Event
core_Meta
  core_WithGRID
  core_WithMaturity
  core_WithPlatformAPI
  core_WithVault
  core_WithVaultLink
core_Resource  [instantiates: core_WithPlatformAPI]

Entity

core_Entity is the abstract root of identifiable, versioned, platform-accessible domain objects. It is never used directly: every entity is either an Artifact or an Activity. It has the identifier slot core_id, whose range is GRID, and it instantiates three core mixins, which allow these class-level annotations:

  • grid — the GRID template of the class (core_WithGRID);
  • maturity — EXPERIMENTAL, PRODUCTION or OBSOLETE (core_WithMaturity); cdm-lint treats a class without the annotation as PRODUCTION;
  • platformAPI / nexarAPI — the Altium 365 Platform API or Nexar GraphQL type of the class (core_WithPlatformAPI).

Artifact

core_Artifact: a persistent data object that is created, stored, versioned and consumed. Artifacts are the things other work refers to or uses. Typical Artifacts in the schema:

Activity

core_Activity: a process or work object — something that happens, uses inputs and produces outputs. Typical Activities in the schema:

Resource

core_Resource is not an Entity. A Resource is a lightweight object that typically exists as part of an Entity: it has no GRID and no versioning lifecycle of its own, but it can have a Platform API type (core_Resource instantiates core_WithPlatformAPI). Examples: BOM lines (pro_BomItem), parameters and variants (des_ProjectParameter, des_ProjectVariant), lifecycle stages and states (plt_LifecycleState), comments (col_Comment), the contents of a device model (dm_Peripheral, dm_PortConfiguration), and the models inside a system model version (system_SdmFunctionalModel).

About half of the Resources have no identifier slot. 27 of the 63 concrete Resources have core_localId, an identifier that is unique only within its context — for example dm_Peripheral, dm_PortConfiguration and system_SdmFunctionalModel; five device-model Resources use a natural key instead, such as the name of a pin (dm_Pin) or a start address (dm_Register).

Event

core_Event is the abstract base for domain events: things that happened, with no GRID and no versioning lifecycle. The schema currently has one event class, cus_ScriptExecutionCompleted.

Mixins

Mixins extend core_Meta and are never used as a parent with is_a.

  • The core mixins are attached with instantiates: core_WithGRID, core_WithMaturity and core_WithPlatformAPI on core_Entity, core_WithPlatformAPI on core_Resource. core_WithVaultLink is attached to one slot (lib_ComponentRevision_template); core_WithVault is defined but not attached anywhere yet.
  • Domain mixins add slots and are attached with mixins, for example plt_HasLifecycle (a lifecycle state, on revision and release classes), plt_SolutionItem (membership in a solution, on des_Project, sft_SoftwareProject, system_ESDDocument and sft_AIModel) and pro_Bom (on the BOM classes).

How to classify a class

The current classification follows these criteria, in this order:

Question If yes Examples
Is it a lightweight object held within another object, with no GRID of its own? core_Resource pro_BomItem, dm_PortConfiguration
Is it a record that something happened rather than a persistent object? core_Event cus_ScriptExecutionCompleted
Is it a project or document that organises ongoing work, or the editable working state of something? core_Activity des_Project, system_ESDDocument, pro_ManagedBOM
Is it a unit of work, a request or the run of a process? core_Activity col_Task, lib_PartRequest, des_RuleCheckExecution
Is it a stored item, revision, snapshot, release or produced output that other work uses? core_Artifact lib_ComponentRevision, system_SdmSystemModelVersion, pro_BomRelease
Is it a platform or catalogue record (user, Workspace, supply part)? core_Artifact plt_User, plt_Workspace, sup_Part

A recurring pattern is a working Activity paired with Artifact snapshots of it:

  • system_SdmSystemModel → system_SdmSystemModelVersion, linked by the slots system_SdmSystemModel_versions and system_SdmSystemModel_latestVersion (which specialise no core relation); the version is described as the state of the system model at a point in time.
  • des_Project → des_ProjectRelease, pro_BomWIP (and so pro_ManagedBOM, pro_ConsolidatedBOM) → pro_BomRelease, plt_Solution → plt_SolutionRelease and sft_SoftwareProject → sft_SoftwareRelease, linked by core_releases. The project release, the BOM release and the solution release are described as snapshots of the project, the BOM and the solution; the software release has no description yet, so for it the pairing rests only on the name and the core_releases slot.

It is a pattern, not a rule that splits design work from released data. Exceptions and open questions, tracked in MODEL-FINDINGS.md:

  • The run of a script (cus_ScriptExecution) is an Artifact, while the run of a rule check is an Activity (MF-073).
  • cus_Workflow is an Activity, but its Platform API type is a workflow definition (MF-026).
  • ins_PartInsight is an Activity without a description, so none of the criteria explains the choice, and its relations do not fit the domains and ranges of the core relations (MF-075).
  • The description of core_Artifact in core.yaml names system models as examples, although system_SdmSystemModel is an Activity (its versions are Artifacts) (MF-077).

Ontological basis

The Artifact/Activity split is aligned with the entity/activity distinction of the W3C provenance ontology PROV-O and the continuant/occurrent distinction of the Basic Formal Ontology (BFO). The mappings are declared in core.yaml and exported to OWL as skos:closeMatch and skos:relatedMatch:

None of them is an exact match:

  • The CDM classes are narrower than the PROV-O classes: they are records on the platform. prov:Entity is also broader in another way — in PROV terms a persisted project, which the CDM models as an Activity, is an entity too.
  • Artifacts are documents, models and data — information that can be copied from one carrier to another. That is closer to BFO's generically dependent continuant than to BFO object (a material entity), but the CDM does not commit to BFO categories, so the mapping is only a related match.
  • BFO process is an occurrent that unfolds in time, and the BFO/RO parthood relations do not let an occurrent have continuants as parts. CDM Activities are persistent, versioned records with Artifact parts (for example req_Project_specifications links a requirements project to its specifications), so this is a related match as well.

core_Entity, core_Resource and core_Event have no mappings. The mappings of the core relations are listed on Relation Types.