← Back to Main Documentation Core Systems Index

Plings Class System

Updated: Sat 26 Jul 2025 20:49:56 CEST - Updated to reflect global class pointer system with cryptographic verification Updated: Fri 12 Jun 2026 22:00:34 CEST - Elevated Identifier–Object Lifecycle to a named foundational principle
Updated: Fri 19 Jun 2026 15:03:36 CEST - Hierarchy is a DAG (not a strict tree) + shallow-taxonomy/properties/derived rule; added Class provenance (manufacturer vs user/community classes) and weighted object↔class edges / related-objects; cross-linked the AI object-classification spec
Updated: Sat 27 Jun 2026 15:52:32 CEST - Noted the first concrete implementation of the user/community class column (class-seeded instances) and that cp is widened to a class reference (non-crypto for community classes); linked ADR-0055/0056/0057 and the class-seeded-instances spec + flow doc
Updated: Thu 02 Jul 2026 18:38:21 CEST - Added “Articles (manufacturer SKUs)” under class provenance (SKU-granularity resolves the shallow-taxonomy-vs-SKU tension explicitly; article_number; crypto-cp-now-verify-later — ADR-0063/0064); marked §9’s Postgres class_pointers schema as aspirational design history (identity lives on the Neo4j node per ADR-0057)
Document Version: 2.3 - Manufacturer articles (SKU-granular classes); §9 schema annotated as aspirational
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, Frontend Developers, Database Architects, Product Managers
Author: Paul Wisén

1. Overview

The Plings Class System is a global hierarchical framework for defining all physical and conceptual objects within the Universal Object Graph System (UOGS). It distinguishes between an object’s blueprint (ObjectClass) and its physical manifestation (ObjectInstance). This separation allows for powerful templateing, inheritance, and tracking of individual items.

Key Innovation: Global Class Pointer System

Migration Note: The Plings class system has evolved from embedded dash-markers to a global class pointer architecture. For complete technical details, see update-class-system.md.

Core Principle: Classes are globally identified by cryptographically-derived class pointers that provide:

  • Unlimited class space: Not constrained by BIP32 wallet limits
  • Cryptographic verification: Manufacturers can’t be counterfeited
  • Offline authentication: POS systems can verify authenticity without internet
  • Global uniqueness: Class pointers are unique across all manufacturers

2. Core Concepts

Principle: Identifier–Object Lifecycle

Identifiers are minted independently of objects. A PlingsIdentifier can exist with no ObjectInstance behind it. An ObjectInstance is materialized lazily — on first scan/use, only when there is utility in having a database record. (This is why factories can mint millions of identifiers offline without pre-registering items — see Producer Delegation.)

A consequence: an identifier’s class pointer (cp) is a class assertion the identifier carries, loosely coupled — it does not require, and is not bound to, a pre-existing object. Attaching a class-specific tag to an existing object is therefore valid; the cp is metadata, not a binding constraint.

ObjectClass

An ObjectClass is a template or blueprint that represents a specific product defined by a manufacturer. Each class is globally identified by one or more cryptographically-derived class pointers that prove manufacturer authenticity.

  • Examples: “IKEA BILLY Bookcase White 80x28x202cm”, “Coca-Cola Classic 355ml Can”, “Apple iPhone 15 Pro Max 256GB Blue”.
  • Global Identity: Each class has one or more 11-character class pointers (e.g., 4K7mX9abDcE) derived from SHA256(manufacturer_pubkey:path_to_pointer)
  • Verification: Class pointers provide cryptographic proof that only the manufacturer could have created this product definition
  • Key Attributes:
    • name and description: Product identification
    • version: Increments with minor updates
    • parent_class: Hierarchy link (e.g., IKEA_BILLY -> Bookcase -> Furniture)
    • manufacturer_organization_id: Links to manufacturer (enables class pointer verification)
    • class_pointers: Array of 11-character pointers identifying this class globally
    • visibility: Controls access (“public”, “private”)
    • components: Required or optional sub-objects
    • capabilities: Potential uses and functions

Class provenance: manufacturer vs user/community classes

A class can arise from two distinct purposes (decided 2026-06-19). The cryptographic class-pointer machinery described throughout this document applies to the manufacturer path; the user/community path is a separate, non-cryptographic namespace:

  Manufacturer class User / community class
Purpose Authoritative instantiation — instances inherit the manufacturer’s verified info/specs so the same data isn’t re-entered per object (anti-double-data) Searchability and sharing information about objects across the community
Identity Cryptographic class pointer (SHA256(manufacturer_pubkey:path)), manufacturer-verified No manufacturer key; a community-owned class node (no class pointer)
Created by The manufacturer A user, assisted by AI classification (see below)

AI-assisted classification (photograph an object → suggested class + properties, match-before-mint) feeds the user/community path. Design: Plings-API/docs/specs/2026-06-19-object-classification-design.md and the admin tooling in class-management-console.md §2.1.

First concrete implementation — class-seeded instances (2026-06-27). The user/community class column now has its first shipped implementation: registering many identical objects at zero per-object cost (one rich class, thin instances that inherit its image/name). With it, cp is widened from “manufacturer crypto pointer” to “class reference” — crypto-derived for manufacturer classes, a stable, unique non-cryptographic id for community classes (uniqueness is the only requirement; the registered :ObjectClass node is the authority, not a signature). See internal/decisions/ADR-0055 (cp widened), ADR-0056 (class imagery + thin-instance inheritance), ADR-0057 (Neo4j canonical for class identity; Postgres images reference the class node). Design: Plings-API/docs/specs/2026-06-26-class-seeded-instances-design.md; flow: Plings-API/docs/flows/class-seeded-instances.md.

Articles (manufacturer SKUs)

The manufacturer column’s concrete shape (2026-07-02) is the article: a SKU-granular manufacturer :ObjectClass — no new entity (ADR-0063). Every sellable variant is its own article class (“Påse grön 10x15cm” ≠ “Påse vit 10x15cm”), each with its own crypto-derived cp and an article_number property (e.g. PL-0001, unique per manufacturer organisation, not globally).

This resolves an earlier latent tension in this document explicitly: the shallow-taxonomy fishing-rod rule (properties over subclasses) governs the community taxonomy; manufacturer articles are SKU-granular leaves under it — which is exactly what this document’s own manufacturer examples (“IKEA BILLY Bookcase White 80x28x202cm”) always showed. Article classes SUBCLASS_OF the shallower community/category classes, and the discriminators (colour, size) are also set as properties so search still works across variants.

Crypto-cp now, verify later: an article’s cp is crypto-derived server-side at creation from the manufacturer’s registered public key + its canonical namespace node’s decimal prefix (normative derivation in ADR-0064) — because the cp is printed on physical tags and can never change. The verification flow (recompute against the published key, class_kind dispatch in the resolver) remains a separate future spec, unchanged from ADR-0055. Flow doc: Plings-API/docs/flows/artikelregister.md; spec: internal/specs/2026-07-02-manufacturer-article-registry-design.md.

Weighted object↔class edges & related objects

The object→class link carries a weight (confidence / strength of fit) — an object relates to a class by degree, not just a boolean — so related objects (“others like this / compatible with this”) can be surfaced ranked by shared classes, capabilities, and functional predicates. (Decided 2026-06-19. The Postgres-vs-Neo4j placement of these weighted edges is an open implementation question; weighted relationships favour Neo4j.)

ObjectInstance

An ObjectInstance is a specific, physical object that exists in the real world. Each instance is based on a specific version of an ObjectClass and can be linked to that class through one of its class pointers. An ObjectInstance can exist without an identifier and can have multiple identifiers pointing to it.

  • Examples: “My IKEA BILLY bookcase #158 from batch 15”, “Coca-Cola Classic can #90000 from Atlanta plant batch 5847”.
  • Class Pointer Link: Instance is connected to its class via the class pointer used in its identifier URL
  • Key Attributes:
    • instance_of: Link to the ObjectClass that defines it
    • class_pointer: The specific 11-character class pointer used for this instance
    • statuses: Current state(s) - multiple can be active (e.g., [“for_sale”, “broken”])
    • owner: Current owner of the physical object
    • part_of: Link to another ObjectInstance it is physically part of
    • hd_path: Full HD wallet path for cryptographic derivation (e.g., “2.3.2.G.3j”)
    • solana_address: The 44-character Solana address for direct payments

PlingsIdentifier

A PlingsIdentifier is a standalone digital entity that points to a specific ObjectInstance through a cryptographically-derived URL. It contains both the HD wallet path (for hierarchy) and the class pointer (for product verification).

  • URL Format: https://s.plings.io?t=q&p={path}&cp={class_pointer}&i={solana_address}
  • Components:
    • path: HD wallet path with NO class information (e.g., “2.3.2.G.3j”)
    • class_pointer: 11-character cryptographic class identifier (e.g., “4K7mX9abDcE”)
    • solana_address: 44-character address for direct payments
  • Verification: The class pointer can be verified offline using manufacturer public keys

The class pointer is an assertion carried by the identifier, not a binding to a specific object — see the Identifier–Object Lifecycle principle above.

For detailed information about identifiers, see Plings Identifier Overview.

These classes form the backbone of the Plings application, modeling the core entities and their interactions within the universal object graph.

3. Key Design Decisions & Use Cases

Based on our discussion, the system will adhere to the following principles:

Feature Implementation
Hierarchy A formal class hierarchy via SUBCLASS_OF. It is a DAG, not a strict tree — a class may extend more than one parent (e.g. a carbon casting rod is both a “Rod” and a “Carbon-fibre item”), reflecting real-world multi-dimensional classification. Keep the taxonomy shallow: encode discriminators (e.g. “5–25 g cast weight”) as properties, not as deep leaf classes; “what it’s good for” (e.g. suitable for perch) is derived/functional, not a class. New classes normally extend an existing parent, but the structure is a DAG, not single-inheritance. (Decided 2026-06-19.)
Component Relations We use a ComponentRequirement subdocument. This allows a class to define what it’s made of (e.g., “requires 2 wheels of type WheelClass”).
Versioning Classes have a version number for minor updates. Significant changes (e.g., new features) result in a new ObjectClass, often inheriting from the old one.
Multi-purpose Objects An object’s potential uses are defined by a capabilities property (e.g., ["BikeLamp", "HelmetLamp"]). This avoids class duplication for different contexts.
Privacy A combination of visibility on the ObjectClass and owner properties on both classes and instances provides granular access control. Class owners define what instance owners can see.
Instance Creation When a user scans a PlingsID, they can choose which sub-components of the object to create as distinct ObjectInstances. This is to conserve data storage.
Class Updates ObjectInstances are linked to a specific class version but are aware of newer versions. The system can notify users of updates to the class definition.

Use Case: Authenticity and Counterfeit Resolution

The decoupled nature of PlingsIdentifier enables powerful verification workflows through dual identifiers and cryptographic verification.

This use case demonstrates how object classes relate to brand protection and anti-counterfeiting measures. For detailed authentication workflows and brand authority specifications, see Brand Authority Specification.

4. Example Flow: A Bicycle with Class Pointer Verification

  1. Base Class: Plings defines a high-level :ObjectClass node with name: "Bicycle".
  2. Manufacturer Class: ACME Inc. creates a new :ObjectClass node with name: "ACME Mountain Bike Model X". This node has:
    • -[:SUBCLASS_OF]-> relationship pointing to the “Bicycle” class node
    • manufacturer_organization_id linking to ACME’s organization record
    • class_pointers: ["3K7mX9abDcE"] - the cryptographic class identifier
  3. Class Pointer Generation: The class pointer 3K7mX9abDcE is generated using: 
    # ACME's path structure: 2.G.2.2 (wallet.manufacturer.category.model)
message = f"{acme_ed25519_pubkey}:2.G.2.2"
class_pointer = base58.encode(SHA256(message)[:8])  # "3K7mX9abDcE"
  4. Production: ACME manufactures 1000 bikes. For each, they create:
    • :ObjectInstance node with class_pointer: "3K7mX9abDcE"
    • :PlingsIdentifier node with path 2.G.2.2.7P.3j (batch 2024, instance 158)
    • URL: https://s.plings.io?t=q&p=2.G.2.2.7P.3j&cp=3K7mX9abDcE&i=A7Kj9mN2pQ8Rt5KdBUoD3f...
  5. Purchase & Verification: A customer scans the QR code:
    • System extracts path 2.G.2.2.7P.3j and class pointer 3K7mX9abDcE
    • Offline Verification: Uses ACME’s public key to verify class pointer authenticity
    • Product Identification: Resolves class pointer to “ACME Mountain Bike Model X”
    • Ownership Transfer: Updates owner property on the :ObjectInstance
  6. Anti-Counterfeiting: Any attempt to forge a class pointer fails because:
    • Only ACME has the private key to generate valid class pointers for path 2.G.2.2
    • POS systems can verify authenticity offline using ACME’s public key
    • Invalid class pointers are immediately detected and flagged

5. Use Case: Ownership of Aggregates (The Container Pattern)

A core challenge is tracking ownership of bulk items without creating millions of database entries (e.g., for individual cans of soda on a pallet). The system handles this through a “container pattern” that relies on a distinction between implicit and explicit ownership.

This use case demonstrates how classes enable sophisticated ownership tracking through component hierarchies. For detailed ownership intelligence and organizational management, see Organization Ownership Intelligence.

6. Use Case: Primary Components and Smart Instantiation

When a user acquires a product that contains multiple items in a box (e.g., a laptop, charger, and manual), the system must be able to distinguish the “main” item from its accessories.

This is achieved by adding an is_primary_component boolean flag to the ComponentRequirement class.

Example Flow: A Laptop Purchase with Class Pointer Verification

  1. Class Definition: A manufacturer defines an ObjectClass for their “Dell XPS 13 Laptop Bundle”:
    • Class Pointer Generation: 7K8mX9abDcE derived from SHA256(dell_pubkey:"2.9.3.4.2")[:8]
    • Path Structure: 2.9.3.4.2 (wallet.dell.electronics.laptops.xps13)
    • Components: Specifies LaptopClass with is_primary_component: true, plus ChargerClass and ManualClass as accessories
  2. Production: Dell manufactures laptop bundles with identifiers like:
    • Path: 2.9.3.4.2.Q.3C (batch Q=25, instance 3C=139)
    • Class Pointer: 7K8mX9abDcE (cryptographically links to Dell XPS 13 class)
    • URL: https://s.plings.io?t=q&p=2.9.3.4.2.Q.3C&cp=7K8mX9abDcE&i=B8kN3mQ7xRt5Kd...
  3. Acquisition & Verification: Customer scans the QR code:
    • Class Verification: System uses Dell’s public key to verify 7K8mX9abDcE is authentic
    • Product Resolution: Class pointer resolves to “Dell XPS 13 Laptop Bundle”
    • Component Discovery: System identifies this is a multi-component product
  4. Smart Prompting: Based on the verified class definition, system prompts: “Congratulations on your authentic Dell XPS 13! Would you like to create separate digital records for:”
    • ✅ Dell XPS 13 Laptop (primary component)
    • ☐ Dell 65W USB-C Charger (accessory)
    • ☐ User Manual (documentation)
  5. Component Instantiation: User selections create separate ObjectInstance nodes, each inheriting the cryptographic authenticity from the verified parent class.

7. Use Case: Rich Spatial Relationships

To accurately model where objects are in the real world, classes work together with the spatial relationship system to define how object instances relate to each other in space.

For detailed information about spatial relationships and how they interact with object classes, see Spatial Relationships System and Spatial Parent-Child Architecture.

8. Use Case: Digital Twin for Industrial Maintenance (The Hydraulic Jack)

The combination of detailed component modeling, the container pattern, and on-demand instantiation allows for powerful “digital twin” use cases, especially for complex equipment repair and lifecycle management. This moves beyond simple ownership tracking into active maintenance and facilitating a circular economy for spare parts.

Example Flow: Repairing a Hydraulic Jack with Verified Components

  1. Manufacturer’s Blueprint: Simplex creates an :ObjectClass for their hydraulic jack:
    • Class Pointer: 9G7mX9abDcE derived from SHA256(simplex_pubkey:"2.G.5.3.2")[:8]
    • Path Structure: 2.G.5.3.2 (wallet.simplex.hydraulics.jacks.model_5ton)
    • Component Classes: Defines 36 official component classes, each with their own class pointers
  2. Initial Purchase: User buys a jack with full cryptographic verification:
    • Path: 2.G.5.3.2.D.4.7ue (batch D=13, instance 4.7ue)
    • Class Pointer: 9G7mX9abDcE (cryptographically proves authentic Simplex jack)
    • URL: https://s.plings.io?t=q&p=2.G.5.3.2.D.4.7ue&cp=9G7mX9abDcE&i=7mK9Px2RtCRJcyPb...
    • Verification: System confirms authenticity using Simplex’s public key
  3. Digital Disassembly & Diagnosis: After years of use, the jack fails:
    • Owner scans jack identifier: path 2.G.5.3.2.D.4.7ue, class pointer 9G7mX9abDcE
    • Class Resolution: System verifies and resolves to “Simplex 5-Ton Hydraulic Jack”
    • Component Blueprint: Displays interactive diagram from verified Simplex class definition
    • Part Identification: Owner identifies “Piston Seal” (#24) as broken component
  4. Component Instantiation with Verification: System creates broken component:
    • New Instance: Creates :ObjectInstance for the specific broken seal
    • Component Class Pointer: 2X8mX9abDcE (Simplex Piston Seal class pointer)
    • Verification Chain: Links to verified Simplex component class definition
    • Relationships: -[:PART_OF]-> main jack, -[:INSTANCE_OF]-> SimplexPistonSeal class
    • Status: ["broken"] with ownership inherited from parent jack
  5. Verified Circular Economy: Cryptographic verification enables trust in spare parts market:
    • Authentic Parts Search: Query for SimplexPistonSeal instances with status ["for_sale"]
    • Seller Verification: Each spare part has class pointer 2X8mX9abDcE verifiable against Simplex’s public key
    • Counterfeit Protection: Fake parts cannot generate valid class pointers without Simplex’s private key
    • Compatibility Guarantee: Class pointer system ensures exact part compatibility

This workflow transforms a physical object into a dynamic digital twin, creating a foundation for a truly circular and repair-focused economy.

9. Class Database Schema

⚠️ ASPIRATIONAL — superseded by reality (annotated 2026-07-02, kept as design history). Ground-truth check against the live databases (2026-07-02): there is no Postgres class_pointers table, and class identity does not live in Postgres. Class identity lives wholly on the canonical Neo4j :ObjectClass node (class_ref, class_kind, owner_org_id, article_number, cp_wallet_version/cp_path) per ADR-0057; class_ref is uniqueness-constrained in Neo4j; the manufacturer pubkey lives in the existing Postgres manufacturer_registry. The cp-registry columns described below are design history — if the future verification spec needs an offline-distributable cp registry, it will add one then. The section is deliberately kept (not deleted) as the record of the original design.

The class system is implemented using both PostgreSQL (for metadata) and Neo4j (for relationships), enhanced with class pointer support:

PostgreSQL Tables

  • object_classes: Stores class definitions, properties, and metadata
  • class_pointers: Maps 11-character class pointers to class definitions (with global uniqueness)
  • object_instances: Stores instance data with class pointer references
  • component_requirements: Defines class component relationships
  • manufacturer_registry: Ed25519 public keys for class pointer verification

Neo4j Relationships

  • [:INSTANCE_OF]: Links object instances to their classes via class pointer
  • [:SUBCLASS_OF]: Creates class inheritance hierarchy
  • [:PART_OF]: Defines component relationships between instances
  • [:VERIFIED_BY]: Links class pointers to manufacturer verification keys

Key Schema Enhancements for Class Pointers

-- New class pointer registry (global uniqueness)
CREATE TABLE class_pointers (
    id UUID PRIMARY KEY,
    class_pointer VARCHAR(15) UNIQUE NOT NULL,  -- 11-character class pointer
    class_id UUID REFERENCES object_classes(id),
    manufacturer_pubkey TEXT NOT NULL,          -- Ed25519 public key
    path_to_pointer VARCHAR(50) NOT NULL,       -- Path used for generation
    verified_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Enhanced object instances with class pointer support
ALTER TABLE object_instances 
ADD COLUMN class_pointer VARCHAR(15),
ADD COLUMN hd_path VARCHAR(100),               -- Full HD path
ADD COLUMN solana_address VARCHAR(44);         -- Direct payment address

For detailed database schema information, see Supabase Core Schema and Neo4j Core Schema.