Design Philosophy
Pletka
Composable semantic modeling for cultural heritage. Build bottom-up, from small reusable pieces to complete descriptions of your domain.
Section I
The Problem
Cultural heritage institutions β museums, archives, libraries β need to describe their collections in structured, interoperable ways. They use ontologies: formal vocabularies that define how things relate to each other. CIDOC-CRM alone has 81 classes and 160 properties. Add extensions like Linked Art, LRMoo, and EDM, and you face a universe of possible paths with little guidance on best practices.
Historically, each institution built their data models from scratch. A curator would study the ontology specification, choose classes and properties, define constraints, and document everything manually. The next institution would do the same work again, often making different choices for the same concepts. When it came time to share or integrate data, the inconsistencies meant months of reconciliation work.
The barrier to entry was high. The cost of mistakes was invisible until integration time. And the collective knowledge of what worked stayed locked in individual heads and institutional wikis.
Section II
Our Building Blocks
Pletka breaks ontology modelling into composable building blocks. You build bottom-up, from small reusable pieces to complete descriptions of your domain.
Fields
A field is the atomic unit. It is an ontological path that starts with a scope class and ends where a user would enter real content β a name, a date, a reference to another entity.
Each field has:
- ◈ An ontology path: the chain of classes and properties from the CRM (or other ontology) that gives this field its formal meaning
- ◈ An expected value type: what kind of content goes at the end of the path β plain text, a date, a URI, a reference to another model, or a term from a controlled vocabulary
- ◈ A multilingual title and description: human-readable context for what this field means and how it should be used
The expected value type is what defines the field's semantic relation. A field that expects a "Model" reference creates a link to another entity. A field that expects a "Concept" connects to a controlled vocabulary. A field that expects a "String" holds literal content. The same ontology path can end with different value types depending on how you want to use it.
By itself, a single field is not very useful. Its power comes from composition.
Categories
Categories are the organisational layer that makes your field library navigable. Without them, you face a flat list of dozens or hundreds of fields. Categories group fields into human-readable sections β "Existence", "Description", "Names and Identifiers", "Technical Metadata" β so users can find what they need.
Categories are not semantic units. They carry no ontological meaning. They are how you organise fields for human consumption: tabs in a form, sections in documentation, chapters in a guide. Each project can organise its categories differently, and when you adopt fields from another project, you can remap their categories to match your own structure.
Collections
Collections are semantic blocks of meaning. They group related fields that share a common ontological context β for example, a "Birth Event" collection gathers all the fields related to E67_Birth: the date, the place, the participants.
Inside a collection, you often want to override the field's title and description. The base field might be called "P7 took place at" (its formal ontology name), but inside a "Birth Event" collection, you would override it to "Place of birth" with a description like "Where this person was born." These overrides make the intent clear without changing the underlying ontological path.
Overrides are what make reuse practical. The same field β same ontology path, same formal meaning β can appear in multiple collections with different names and descriptions that match each context. The ontological rigour stays intact underneath.
Models
A model is a semantic unit of meaning. It represents a real-world entity type you want to describe β a Person, an Object, a Place, an Event. A model has a scope class (the CRM class it represents) and bundles collections and fields together with its own layer of overrides.
Model-level overrides can do more than rename. They can change the expected value type of a field (narrowing what content is accepted), mark fields as required or optional, set minimum and maximum occurrences, or hide fields that don't apply in this context.
The Weave
The weave is the complete picture: all your models, their collections and fields, the relationships between models, and the overrides that make everything fit your specific use case. A weave is a slice of the ontological universe β the part you have chosen to describe, with the precision you need.
If a model describes one entity type, the weave describes how those entity types relate to each other. A "Person" model references a "Place" model through a birth event. An "Object" model references a "Person" model through a production event. The weave captures these connections.
Section III
Relations and Expected Value Types
Fields don't exist in isolation. They create connections β between entities, between concepts, between data and meaning. The expected value type at the end of a field's ontology path determines what kind of connection it makes.
| Expected Value Type | What It Connects To | Example |
|---|---|---|
| String | Literal text content | A title, a description, a note |
| Date | A temporal value | A birth date, a creation date |
| URI | An external web resource | A link to a Wikipedia page |
| Model | Another entity in your weave | A Person linked from a Production event |
| Collection | A structured block of fields | An Address block within a Place |
| Concept | A controlled vocabulary term | A material type from the AAT thesaurus |
| GeoJSON | Geographic coordinates | A location on a map |
When a field's expected value type is "Model", it creates a semantic relation between two entity types. This is how the weave connects: an Object's "produced by" field points to a Person model. A Person's "born at" field points to a Place model. The expected value types are the joints that hold the weave together.
These value types can be overridden at the model level. A base field might accept any Model reference, but in a specific model you can narrow it to require a particular model type β for example, the "created by" field on an Object must reference a Person or Group, not a Place. This layered constraint system keeps the base fields reusable while letting each model enforce its own rules.
Section IV
The Power of Overrides
Overrides are the mechanism that makes composition and reuse work. Without overrides, you would need a separate field for every context β "Person Name", "Object Title", "Place Name", "Event Label" β even though they all use the same ontology path (P1_is_identified_by). With overrides, you build one field and adapt it everywhere.
The Override Chain
Layer 1
Base Field
The canonical definition with its ontology path, default name, and default expected value type
Layer 2
Collection Override
Rename and redescribe the field for the collection's context
Layer 3
Model Override
Further rename, change the expected value type, set cardinality constraints, or mark as required
The most specific override wins. If no override exists at a level, the system falls back to the next layer.
This means the same field β the same ontological path, the same formal semantics β can appear as "Title" in an Object model, "Name" in a Person model, and "Label" in a Concept model. The interoperability is preserved at the ontology level. The human understanding is preserved at the override level.
Section V
Composition and Reuse
Our platform focuses on composition and reuse. Instead of building from scratch, you compose from a growing library of patterns that the community has already validated.
Think of it like neural pathways. Every time a field path is adopted by another project, the groove gets deeper. The more projects that use a particular way of describing "production events" or "object dimensions", the more confident you can be that this path is well-established and interoperable.
We surface these patterns through weighted suggestions β similar to how Google's PageRank algorithm ranked web pages by how many other pages linked to them. The most-adopted patterns float to the top. This makes reuse the path of least resistance. You can create something entirely new, but the platform gently guides you toward patterns that others have already proven to work.
Starting a Project
You start by creating a project and selecting which ontologies and extensions you want to work with. This filters your suggestions β if you choose CIDOC-CRM with the Linked Art profile, you see fields, collections, and models that are relevant to art museum data. If you add LRMoo, bibliographic patterns become available too.
You can select a parent project as your foundation. All the parent's published fields, collections, and models become available in your library. You don't copy them β you reference them. When you adopt a pattern, you can override names and descriptions for your context. If the parent updates their patterns and publishes a new version, you can choose to incorporate those changes.
Everything you adopt or override becomes part of your weave. The library holds all the available patterns. Your weave is what you have actively chosen to use and how you have adapted it.
Composing Your Weave
With your library populated, you compose what you want to describe. Browse fields by category. Adopt collections that match your needs. Assemble models from collections and individual fields. The field paths under the overrides drive the interoperability β no matter how you rename things for your users, the ontological paths stay consistent. The suggestion engine learns from the community. Fields that are commonly used together appear as recommendations. Collections that have been adopted by many projects rank higher. Patterns that work well together are surfaced. You benefit from every project that came before yours.
Section VI
Making It Accessible
All of this is still technical. How does it help the non-technical users who actually enter data, review records, or manage collections?
Overrides support examples. For each field in a collection or model, you can provide sample values that show users what correct data looks like. "For the Title field, enter the object's primary display name, e.g., 'The Night Watch' or 'Portrait of a Lady'."
These examples, combined with the multilingual descriptions on overrides, become the basis for generated documentation. Pletka can produce human-readable guides that explain each model: what fields it has, what each field means, what kind of data goes there, and what good examples look like. This is how end-users understand what you have built to describe your information β without ever seeing an ontology path or a CRM class number.
Section VII
Generators
Once you have a well-described weave, you might ask: and then what? Hand-translating your models into implementation formats is cumbersome and error-prone. So Pletka offers generators that take a weave and produce reusable output formats:
By implementing the generator interface, you can add new output formats for your specific needs. The generator reads your weave β models, collections, fields, overrides, expected value types β and produces the output. Change your weave, regenerate, and your implementation formats stay in sync.
Section VIII
Users and Organisations
Individual users can create projects, build models, and publish their work. This is enough for researchers, freelance consultants, or small teams.
Organisations β museums, archives, library networks β are users with additional capabilities. They can manage members with different roles (curators, reviewers, editors), control which projects are visible internally versus publicly, and coordinate work across teams. The model follows what developers know from GitHub: an organisation owns projects, members have roles, and visibility is controlled per project.
For the platform, an organisation is a user with more features. The same composition and reuse mechanisms work at both levels. An organisation's projects can serve as parent projects for their member institutions, creating a shared foundation that individual projects extend and adapt.
Section IX
Versioning
Things change. Fields get refined, new collections are added, models evolve as understanding deepens. How do you keep track of what changed and why?
Pletka adopts version control concepts from software development β specifically, the distributed model behind Git and GitHub:
Branches
Where you actively work on changes. Your draft modifications don't affect anyone else until you are ready.
Merge requests
Let collaborators review proposed changes before they take effect. Reviewers can comment, suggest modifications, and approve or request revisions.
Releases
Mark specific versions as stable and published. Other projects can only adopt from published releases β they never see your work-in-progress.
History
Records every change with who made it, when, and why. You can compare any two versions and see exactly what changed.
Under the hood, Pletka stores data in both a database (for fast querying and the web interface) and a Git-backed filesystem (for full history and distributed operation). The Git layer means your work is never locked into a single platform. If Pletka the service disappears, your ontology models, version history, and collaboration records remain intact and portable.
Section X
The Future
We are building toward full collaborative workflows on the platform itself: issues for tracking decisions and open questions, comments on specific fields or models, task assignment for team coordination. This mirrors how development teams work on GitHub β making the work, the decisions, and the reasoning visible and transparent.
The goal is that a new team member can look at a project's history and understand not just what was modelled, but why each choice was made and who made it.
Appendix A
Building "Names and Identifiers" from Scratch
This walkthrough shows how Pletka's building blocks compose in practice. We will build a "Names and Identifiers" category following the Linked Art pattern, then show how the same fields work in two different models with different overrides.
1 Create the Fields
We start with the atomic units β individual ontology paths that end where users enter content.
Field: "Appellation Content"
Path: P1_is_identified_by → E33_E41_Linguistic_Appellation → P190_has_symbolic_content
Expected: String — The textual content of a name or title
Field: "Appellation Type"
Path: P1_is_identified_by → E33_E41_Linguistic_Appellation → P2_has_type → E55_Type
Expected: Concept (from Getty AAT) — Classification of this name
Field: "Appellation Language"
Path: P1_is_identified_by → E33_E41_Linguistic_Appellation → P72_has_language → E56_Language
Expected: Concept — The language this name is expressed in
Field: "Identifier Content"
Path: P1_is_identified_by → E42_Identifier → P190_has_symbolic_content
Expected: String — A formal identifier (accession number, catalogue number, etc.)
Field: "Identifier Type"
Path: P1_is_identified_by → E42_Identifier → P2_has_type → E55_Type
Expected: Concept (from Getty AAT) — Classification of this identifier
Notice that these fields are generic. They say nothing about objects, people, or any specific entity. The specificity comes from overrides.
2 Create the Collections
We group related fields into semantic blocks.
Collection: "Name"
Context: E33_E41_Linguistic_Appellation
| Field | Override Name | Override Description |
|---|---|---|
| Appellation Content | Name | The display name |
| Appellation Type | Name Type | Primary, alternative, or former name |
| Appellation Language | Language | The language of this name |
Collection: "Identifier"
Context: E42_Identifier
| Field | Override Name | Override Description |
|---|---|---|
| Identifier Content | Identifier | The identifier value (e.g., '1990.45.2') |
| Identifier Type | Identifier Type | What kind of identifier this is |
3 Create the Category
Category: "Names and Identifiers"
Canonical order: 1 (appears first in forms)
Description: How this entity is named and formally identified
4 Use in an Object Model
Model: "Object"
Scope: E22_Human-Made_Object
| Collection | Field | Model Override | Notes |
|---|---|---|---|
| Name | Name | Title | Objects have titles, not names |
| Name | Name Type | Title Type | Primary title, alternative title |
| Name | Language | no override | Keeps collection name |
| Identifier | Identifier | Accession Number | Narrows the description |
| Identifier | Identifier Type | hidden | Only one type applies |
A curator filling out an Object record sees: "Title" (required), "Title Type", "Language", "Accession Number" (required). Clean, focused, purpose-built for objects.
5 Use in a Person Model
Model: "Person"
Scope: E21_Person
| Collection | Field | Model Override | Notes |
|---|---|---|---|
| Name | Name | no override | "Name" works for people |
| Name | Name Type | no override | Primary name, birth name, married name |
| Name | Language | no override | |
| Identifier | Identifier | ULAN ID | Narrows to artist identifiers |
| Identifier | Identifier Type | hidden | Fixed to ULAN type |
A registrar filling out a Person record sees: "Name" (required), "Name Type", "Language", "ULAN ID" (optional). Same underlying fields, completely different user experience.
What We Built
Fields (5 generic)
Collection: "Name" (3 fields, overridden)
Category: "Names and Identifiers"
Used in: Object (as "Title"), Person (as "Name")
Collection: "Identifier" (2 fields, overridden)
Category: "Names and Identifiers"
Used in: Object (as "Accession Number"), Person (as "ULAN ID")
Five fields. Two collections. One category. Used in two models with completely different user-facing names and constraints. The ontological paths are identical β data from both models is interoperable. The user experience is tailored to each context.
This is what composition and reuse look like in practice. Every project that adopts these fields deepens the grooves. Every override adds clarity without breaking compatibility.