RIPP

Build fast. Ship safely. Regenerate always.

Schema Documentation

RIPP v1.0 Schema Documentation

The RIPP JSON Schema defines the structure and validation rules for RIPP packets.

Schema Location

URL: https://dylan-natter.github.io/ripp-protocol/schema/ripp-1.0.schema.json

Repository: schema/ripp-1.0.schema.json

Schema Overview

The RIPP schema is a JSON Schema Draft 07 document that validates:

Using the Schema

In VS Code

Add to .vscode/settings.json:

{
  "yaml.schemas": {
    "https://dylan-natter.github.io/ripp-protocol/schema/ripp-1.0.schema.json": ["**/*.ripp.yaml"]
  }
}

In JetBrains IDEs

  1. Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings
  2. Add schema URL and file pattern *.ripp.yaml

Programmatic Validation

Node.js (Ajv):

const Ajv = require('ajv');
const schema = require('./schema/ripp-1.0.schema.json');

const ajv = new Ajv();
const validate = ajv.compile(schema);

const valid = validate(yourPacketData);
if (!valid) {
  console.log(validate.errors);
}

Python (jsonschema):

from jsonschema import validate
import json

with open('schema/ripp-1.0.schema.json') as f:
    schema = json.load(f)

validate(instance=your_packet, schema=schema)

Schema Structure

Root Properties

Property Type Required Description
ripp_version string Yes Must be “1.0”
packet_id string Yes Unique ID (kebab-case)
title string Yes Human-readable title
created string (date) Yes ISO 8601 date
updated string (date) Yes ISO 8601 date
status enum Yes draft | approved | implemented | deprecated
level integer Yes 1, 2, or 3
purpose object Yes See Purpose section
ux_flow array Yes See UX Flow section
data_contracts object Yes See Data Contracts section

Conditional Requirements

The schema uses allOf with if/then to enforce level-based requirements:

Section Schemas

Purpose

{
  "type": "object",
  "required": ["problem", "solution", "value"],
  "properties": {
    "problem": { "type": "string", "minLength": 1 },
    "solution": { "type": "string", "minLength": 1 },
    "value": { "type": "string", "minLength": 1 },
    "out_of_scope": { "type": "string" },
    "assumptions": { "type": "array", "items": { "type": "string" } },
    "references": { "type": "array" }
  }
}

UX Flow

Array of steps, each requiring:

Data Contracts

Must have at least inputs or outputs. Each entity has:

Each field requires:

API Contracts (Level 2+)

Array of endpoints, each requiring:

Permissions (Level 2+)

Array of permission definitions, each requiring:

Failure Modes (Level 2+)

Array of failure scenarios, each requiring:

Audit Events (Level 3)

Array of events, each requiring:

NFRs (Level 3)

Object with at least one of:

Acceptance Tests (Level 3)

Array of tests, each requiring:

Validation Rules

Format Validations

Pattern Validations

Enum Validations

Custom Extensions

RIPP allows custom sections via additionalProperties: true at the root level.

You can add organization-specific fields:

ripp_version: '1.0'
# ... standard fields ...

# Custom section (not part of RIPP spec)
custom_tracking:
  jira_ticket: 'PROJ-123'
  team: 'Platform'

Validators will not fail on unknown fields, ensuring forward compatibility.

Schema Evolution

Versioning

The schema follows RIPP spec versioning:

Backward Compatibility

Within v1.x:

Migration

When RIPP v2.0 is released, a migration guide and updated schema will be provided.

Downloading the Schema

Direct download:

curl -O https://dylan-natter.github.io/ripp-protocol/schema/ripp-1.0.schema.json

From repository:

git clone https://github.com/Dylan-Natter/ripp-protocol.git
cd ripp-protocol/schema

Schema Validation Tools

Contributing to the Schema

Schema changes require:

  1. Opening a spec change issue
  2. Community discussion
  3. Approval from maintainers
  4. Updating both SPEC.md and schema file
  5. Version increment

See CONTRIBUTING.md.

The schema is the contract. Validate early. Validate often.