JSON Schema and Reusable Component Library

Objective

Refactor OSSA 1.0 schema to use JSON Schema $defs for improved reusability, maintainability, and to establish a component library that can be referenced by external projects.

Problem Statement

Current schema has duplicated definitions and lacks reusable components. External projects wanting to reference OSSA schema components (like CapabilitySchema, RuntimeSchema) cannot easily extract and reuse them.

Technical Approach

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OSSA 1.0 Agent Schema",
  "type": "object",
  "required": ["ossaVersion", "agent"],
  "properties": {
    "ossaVersion": {
      "type": "string",
      "pattern": "^1\\.0$",
      "description": "OSSA specification version"
    },
    "agent": {
      "$ref": "#/$defs/Agent"
    }
  },
  "$defs": {
    "Agent": {
      "type": "object",
      "required": ["id", "name", "version", "role", "runtime", "capabilities"],
      "properties": {
        "id": { "$ref": "#/$defs/AgentId" },
        "name": { "type": "string", "minLength": 1 },
        "version": { "$ref": "#/$defs/SemVer" },
        "role": { "$ref": "#/$defs/AgentRole" },
        "runtime": { "$ref": "#/$defs/Runtime" },
        "capabilities": {
          "type": "array",
          "items": { "$ref": "#/$defs/Capability" },
          "minItems": 1
        },
        "dependencies": {
          "type": "array",
          "items": { "$ref": "#/$defs/AgentDependency" }
        },
        "policies": { "$ref": "#/$defs/Policies" }
      }
    },
    "AgentId": {
      "type": "string",
      "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
      "minLength": 1,
      "maxLength": 253,
      "description": "DNS-1123 subdomain compatible identifier"
    },
    "SemVer": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
      "description": "Semantic version (semver 2.0.0)"
    },
    "AgentRole": {
      "type": "string",
      "enum": [
        "compliance", "chat", "orchestration", "audit",
        "workflow", "monitoring", "data_processing",
        "integration", "development", "custom"
      ]
    },
    "Runtime": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["docker", "k8s", "local", "serverless", "edge"]
        },
        "image": { "type": "string" },
        "resources": { "$ref": "#/$defs/ResourceRequirements" }
      }
    },
    "Capability": {
      "type": "object",
      "required": ["name", "description"],
      "properties": {
        "name": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
        "description": { "type": "string" },
        "input_schema": { "$ref": "#/$defs/SchemaReference" },
        "output_schema": { "$ref": "#/$defs/SchemaReference" }
      }
    },
    "SchemaReference": {
      "oneOf": [
        { "type": "object" },
        { "type": "string", "format": "uri-reference" }
      ]
    },
    "ResourceRequirements": {
      "type": "object",
      "properties": {
        "cpu": { "type": "string", "pattern": "^[0-9]+m?$" },
        "memory": { "type": "string", "pattern": "^[0-9]+(Mi|Gi)$" },
        "gpu": { "type": "integer", "minimum": 0 }
      }
    },
    "AgentDependency": {
      "type": "object",
      "required": ["agentId", "version"],
      "properties": {
        "agentId": { "$ref": "#/$defs/AgentId" },
        "version": { "type": "string" },
        "optional": { "type": "boolean", "default": false }
      }
    },
    "Policies": {
      "type": "object",
      "properties": {
        "compliance": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "fedramp-low", "fedramp-moderate", "fedramp-high",
              "soc2-type1", "soc2-type2", "hipaa", "gdpr"
            ]
          }
        },
        "encryption": { "type": "boolean", "default": false },
        "audit_logging": { "type": "boolean", "default": false }
      }
    }
  }
}

Benefits

1. Reusability: External projects can reference #/$defs/Capability
2. Maintainability: Single source of truth for each component
3. Composability: Easy to extend and build new schemas
4. Documentation: Each $def becomes a standalone component doc

Acceptance Criteria

• All inline schemas moved to $defs
• Each $def has comprehensive description
• External referencing tested (e.g., $ref: 'ossa-1.0.schema.json#/$defs/Capability')
• All existing tests pass with new structure
• Documentation generated for each $def component
• README updated with $defs reference guide
• Backwards compatibility maintained

Files to Modify

• spec/ossa-1.0.schema.json - Main schema refactoring
• docs/schema-components.md - Component reference documentation