Skip to content

sdd-philosophy.md

Latest commit

 

History

History
257 lines (181 loc) · 7.66 KB

sdd-philosophy.md

File metadata and controls

257 lines (181 loc) · 7.66 KB

SDD Philosophy

Core Claim

JSON Schema Draft-07 is a DSL. The ecosystem misidentified it as a validator config. SDD uses it as what it is — an Object DSL — and writes class definitions in it.

JSON Schema Is a DSL

A DSL (Domain-Specific Language) requires four elements: a type system, composition, logic, and control flow.

Draft-07 has all four.

DSL Element       Draft-07
──────────────────────────────────────────────────
Type system       type (string, number, integer, boolean, array, object, null)
                  format (email, uri, date-time, ...)
                  enum, const
                  minimum, maximum, minLength, maxLength, pattern

Composition       properties, items, additionalProperties
                  definitions, $ref
                  required, dependencies

Logic             allOf  — AND
                  anyOf  — OR
                  oneOf  — XOR
                  not    — NOT

Control flow      if / then / else

Four elements present. JSON Schema Draft-07 is a complete declarative language.

This is not a metaphor. allOf computes conjunction. oneOf computes exclusive disjunction. if/then/else branches on a condition. $ref resolves a reference. These are language operations, not configuration entries.

Comparison with other DSLs:

SQL     →  relational data DSL    (SELECT, JOIN, WHERE = operations on relations)
CSS     →  presentation DSL       (selectors, properties, cascade = operations on elements)
Regex   →  pattern matching DSL   (alternation, quantifiers, groups = operations on strings)
Draft-07 →  Object DSL            (allOf, oneOf, if/then = operations on objects)

SQL is not "a query config file." CSS is not "a style config file." JSON Schema is not "a validator config file."

Each is a DSL. You write programs in it. An engine executes them.

The Misidentification

The ecosystem read JSON Schema as a validator configuration format:

Developer writes schema  →  validator reads it  →  returns true/false

This reduces a DSL to one consumer. It is the same mistake as treating SQL as "a SELECT tool" — ignoring DDL, DCL, and TCL.

JSON Schema can express:

  • Object structure and constraints (what validators use)
  • Conditional logic over object state (if/then/else)
  • Exclusive dispatch (oneOf — exactly one branch matches)
  • Composition by reference (allOf + $ref)
  • Negation and exclusion (not)

A validator consumes the first. The rest go unused — not because they lack power, but because no one built toolchains for them.

The Origin: JSON Is a JS Object

JavaScript objects carry state and behavior together:

const User = {
  email: "alice@example.com",
  age: 30,

  is_adult()  { return this.age >= 18 },
  normalize() { this.email = this.email.toLowerCase() }
}

JSON was created to serialize JS objects for transport. Serialization dropped methods — an engineering compromise, not a design philosophy.

JS Object  →  serialize  →  JSON        (methods stripped for transport)
JSON       →  schema     →  Object DSL  (methods expressible as Draft-07 logic)

JSON Schema is not an independent invention. It was built to describe JS object structure. The DSL elements it carries — logic, branching, composition — are the declarative equivalents of what JS methods do imperatively.

Three Bloodlines

1. Lisp: Data = Code

Program and data share one representation (homoiconicity).

; This is data
'(normalize validate enrich)

; This is also code — same syntax, same structure
(normalize (validate (enrich raw-input)))

One notation. Read as data or execute as code — context decides.

2. Object: State + Behavior as One Unit

Before OOP buried it under inheritance hierarchies, the original insight was simple:

Object = state (fields) + behavior (methods)

A class definition declares both together. They belong to the same entity.

3. JSON Schema: An Object DSL Without a Name

Draft-07 carries full logical expressiveness from its JS object origin. But it was never given a name as a DSL, never treated as a programming language.

The validator community called it "a schema." The API community called it "a spec." Neither recognized that allOf, oneOf, if/then/else constitute a language.

From DSL to Class Definition

Draft-07 as a DSL can express state and logic. But a class definition needs three more namespaces that serialization stripped:

What JS Objects Had What Draft-07 Has What's Missing
Fields with constraints properties, required, type Nothing — covered
Method bodies (logic) allOf, oneOf, if/then/else Nothing — covered
Method namespace — Where to attach methods to the class
Test intent — Which boundaries matter
Semantic context description (unstructured) Structured intent for toolchain + LLM

Draft-07 has the logic to write method bodies. It lacks three namespaces to organize them into a class.

SDD adds exactly three x- extensions:

x-methods  →  method namespace    (body = Draft-07 logic)
x-tests    →  test namespace      (scenario tags per method)
x-docs     →  semantic namespace  (intent, category, notes)

Nothing is invented. The DSL already exists. SDD adds namespaces so the DSL can express a complete class.

The Result

{
  "title": "User",
  "type": "object",

  "properties": {
    "email": {"type": "string", "format": "email"},
    "age":   {"type": "integer", "minimum": 0}
  },

  "x-methods": {
    "is_adult": {
      "properties": {"age": {"minimum": 18}}
    },
    "normalize": {
      "if":   {"properties": {"email": {"pattern": "[A-Z]"}}},
      "then": {"properties": {"email": {"pattern": "^[a-z]"}}}
    }
  },

  "x-tests": {
    "is_adult": ["age_below_18", "age_exactly_18", "age_above_18"],
    "normalize": ["uppercase_email", "already_lowercase", "empty_email"]
  },

  "x-docs": {
    "intent": "Core user entity. Email is the canonical identifier.",
    "category": "auth",
    "notes": "Age is optional; absence means unknown, not zero."
  }
}

properties — state, written in the DSL's type system. x-methods — behavior, written in the DSL's logic operators. x-tests — test intent, declaring which boundaries matter. x-docs — semantic context, structured for toolchain and LLM.

One document. One DSL. One class definition.

Dual Execution Engine

A DSL needs an engine to execute it. JSON Schema has two:

Toolchain (mechanical)  →  evaluates Draft-07 logic against data
LLM (semantic)          →  reads x-docs + structure, understands intent

Both consume the same document. Neither needs a translation layer. The schema is the program. The engines run it.

What This Is Not

  • Not a validator config (validation is one operation the DSL can express)
  • Not a code generator (the DSL is executed directly, not compiled)
  • Not a documentation format (behavior is executable, not descriptive)
  • Not a new language (Draft-07 is the DSL; SDD adds three namespaces to it)

Summary

JSON Schema Draft-07         =  Object DSL (type system + logic + composition + control flow)
The ecosystem's reading      =  validator config (one consumer of the DSL)
SDD's reading                =  class definition language (full use of the DSL)

What Draft-07 already has    =  state definition + method body logic
What SDD adds                =  three namespaces (x-methods, x-tests, x-docs)
What the result is           =  one JSON document = one complete class definition

JSON Schema was always a DSL. SDD uses it as one.