layer-07-data-model

name	LAYER_07_DATA_MODEL
description	Expert knowledge for Data Model Layer modeling in Documentation Robotics
triggers	["JSON Schema","data model","schema","object schema","data structure","properties","validation","data type"]
version	0.8.3

Data Model Layer Skill

Layer Number: 07 Specification: Metadata Model Spec v0.8.3 Purpose: Defines logical data structures using JSON Schema Draft 7, specifying entities, properties, validation rules, and data governance.

---

Layer Overview

The Data Model Layer captures logical data structures:

• SCHEMAS - Object, array, string, numeric schemas
• VALIDATION - Type constraints, required fields, patterns, ranges
• COMPOSITION - Schema combinations (allOf, anyOf, oneOf, not)
• GOVERNANCE - Data classification, PII, retention policies
• INTEGRATION - Links to business objects, database tables, API operations

This layer uses JSON Schema Draft 7 (industry standard) with custom extensions for cross-layer traceability.

Central Entity: The ObjectSchema (defining an object structure) is the core modeling unit.

---

Entity Types

CLI Introspection: Run dr schema types data-model for the authoritative, always-current list of node types. Run dr schema node <type-id> for full attribute details on any type.

Core JSON Schema Entities (9 types)

Entity Type	Description
JSONSchema	Root schema document
ObjectSchema	Defines object structure with properties
ArraySchema	Defines array with items and constraints
StringSchema	String validation (length, pattern, format)
NumericSchema	Number/integer validation (min, max, multipleOf)
SchemaComposition	Combines schemas (allOf, anyOf, oneOf, not)
SchemaDefinition	Named reusable type for shared use in definitions blocks
SchemaProperty	Individual property definition
Reference	$ref to other schemas

Note: Data governance (x-data-governance) and database mapping (x-database) are cross-layer extension attributes, not node types. Set them directly on the schema element they describe — on an objectschema for table-level mapping, or on a schemaproperty for field-level governance (e.g., marking an individual email property as PII).

---

Type Decision Tree

Use this decision tree before assigning a type to any code pattern.

• Is this a root JSON Schema document with $schema, $id, and type fields at the top level? → data-model.jsonschema
• Is this primarily a schema combinator using allOf, anyOf, oneOf, or not (even if it also has properties)? → data-model.schemacomposition
• Is this a reusable named type declared in a definitions block (has title and type)? → data-model.schemadefinition
• Is this an object structure with type: object and properties? → data-model.objectschema
• Is this an array definition with items, minItems, maxItems, uniqueItems, or contains? → data-model.arrayschema
• Is this a string validation rule with minLength, maxLength, pattern, or format? → data-model.stringschema
• Is this a number/integer validation rule with minimum, maximum, exclusiveMinimum, exclusiveMaximum, or multipleOf? → data-model.numericschema
• Is this a standalone $ref pointer with no additional constraints? → data-model.reference
• Is this an inline field declaration within an objectschema, carrying its own constraints (title, description, readOnly, default, const, etc.) alongside or instead of a $ref? → data-model.schemaproperty

---

Common Misclassifications

Misclassification	Correct Classification	Why
Modeling x-data-governance or x-database as their own elements	Set as extension attributes on the relevant schema element (objectschema or schemaproperty)	These are cross-layer extension attributes, not spec node types
Using objectschema for a reusable definition in a definitions block	schemadefinition	definitions entries are named, reusable definitions; objectschema is for structural instances
Using schemadefinition for a top-level schema document	jsonschema	A root document with $schema and $id is jsonschema, not a definition
Using schemaproperty for a standalone string/numeric/array type	stringschema / numericschema / arrayschema	Use the specific schema type when the constraint set is rich enough to stand alone; use schemaproperty only for inline field declarations within an objectschema
Using objectschema for a schema that uses allOf to extend another	schemacomposition	When the primary purpose is combining or extending schemas, classify as schemacomposition — even if the schema also declares properties
Using schemaproperty for a bare $ref with no other constraints	reference	A standalone $ref with nothing else is a reference; use schemaproperty only when the field also carries its own constraints (title, description, readOnly, default, etc.)

---

When to Use This Skill

Activate when the user:

• Mentions "data model", "schema", "JSON Schema", "data structure"
• Wants to define object structures, properties, or validation rules
• Asks about data types, constraints, or data governance
• Needs to model entities like User, Order, Product, etc.
• Wants to link data models to APIs or databases

---

Cross-Layer Relationships

Outgoing (Data Model → Other Layers):

• x-business-object-ref → Business Layer (what business concept does this represent?)
• x-database → Data Store Layer (how is this stored physically?)
• x-data-governance → Security Layer (classification, PII, retention)
• x-apm-data-quality-metrics → APM Layer (data quality monitoring)

Incoming (Other Layers → Data Model):

• API Layer → Data Model (request/response schemas via $ref)
• UX Layer → Data Model (form validation rules)
• Testing Layer → Data Model (input constraints for test partitioning)

---

Common Commands

# Add object schema
dr add data-model objectschema "User" --description "User object schema"

# List data models
dr list data-model --type objectschema

# Validate data model layer
dr validate --layers data-model

# Export as JSON Schema
dr export jsonschema --layers data-model

---

Example: User Schema

id: data-model.objectschema.user
name: "User Schema"
type: objectschema
properties:
  type: object
  required: [id, email, username]
  properties:
    id:
      type: string
      format: uuid
      description: "Unique user identifier"
    email:
      type: string
      format: email
      description: "User email address"
      x-data-governance:
        classification: confidential
        pii: true
    username:
      type: string
      minLength: 3
      maxLength: 50
      pattern: "^[a-zA-Z0-9_-]+$"
    created_at:
      type: string
      format: date-time
    roles:
      type: array
      items:
        type: string
      description: "User role assignments"
  x-business-object-ref: business.actor.user
  x-database:
    table: users
    schema: public

---

Coverage Completeness Checklist

Before declaring data-model layer extraction complete, verify each type was considered:

• arrayschema — Array definitions with item constraints (e.g., list of strings, paginated results)
• jsonschema — Root schema documents (top-level $schema + $id declarations)
• numericschema — Numeric validation rules (prices, counts, scores with min/max/multipleOf)
• objectschema — Object structures with named properties (entities, payloads, records)
• reference — $ref pointers to shared or external schemas
• schemacomposition — Combinators (allOf for inheritance, anyOf/oneOf for polymorphism)
• schemadefinition — Reusable named definitions in definitions blocks
• schemaproperty — Individual field definitions within object schemas
• stringschema — String validation rules (lengths, patterns, formats like email/uuid/date-time)

If any type has ZERO elements, explicitly decide: "This type doesn't apply to this codebase" with reasoning.

---

Modeling Best Practices

• Always specify type on schema elements — validation fails without it
• Break complex schemas into reusable schemadefinition entries and reference them via $ref
• Mark PII and sensitive fields with x-data-governance on the relevant schemaproperty or objectschema
• Add x-business-object-ref to link to the Business Layer and x-database to link to the Data Store Layer
• Use format for semantic string types (email, uuid, date-time, uri) rather than custom pattern where a standard format exists