Public Schema Repository

A centralized repository for public schemas, configurations, and API contracts used across at American Airlines.

Overview

This repository contains JSON schemas and YAML configuration templates for various platform services, ensuring consistency and validation across deployments.

Repository Structure

├── kpaas/                      # Kubernetes Platform as a Service schemas
│   ├── conductor.yaml          # Schema for long-running jobs and CronJobs
│   └── webapps.yaml           # Schema for web application deployments
├── ping-authentication/        # Authentication service schemas
│   └── schema.json            # Configuration schema for Ping Authentication library
└── README.md                  # This file

Schemas

KPaaS (Kubernetes Platform as a Service)

Conductor Schema

• File: kpaas/conductor.yaml
• Purpose: Defines the schema for long-running jobs triggered by events or CronJobs
• API Version: runway.aa.com/v1alpha1
• Kind: Conductor

Key features:

• Container image and tag specifications
• Secrets management configuration
• Metadata and labeling standards
• Integration with AA ecosystem via runway.aa.com/aa-app-shortname label

WebApp Schema

• File: kpaas/webapps.yaml
• Purpose: Defines the schema for web application deployments
• API Version: runway.aa.com/v1alpha1
• Kind: WebApp

Key features:

• Cloud ingress configuration
• Backstage integration support
• Proxy buffer and header buffer settings
• Annotation-based configuration management

Ping Authentication

Configuration Schema

• File: ping-authentication/schema.json
• Purpose: JSON schema for Ping Authentication library configuration
• Schema Version: draft/2020-12/schema

Key features:

• Ping Federate authority configuration
• Client authentication settings
• Role-based access control
• Environment-specific configurations
• Feature flags integration

Usage

For Developers

1. Validation: Use these schemas to validate your configuration files before deployment
2. Documentation: Reference these schemas to understand required and optional fields
3. IDE Support: Configure your IDE to use these schemas for auto-completion and validation

For Platform Teams

1. Standards Enforcement: Use these schemas to ensure consistent configuration across teams
2. API Evolution: Update schemas here when making breaking changes to platform APIs
3. Documentation: Keep schemas up-to-date with platform capabilities

Schema Validation

Using JSON Schema Validators

For JSON schemas (like ping-authentication):

# Using ajv-cli (install with: npm install -g ajv-cli)
ajv validate -s ping-authentication/schema.json -d your-config.json

Using YAML Schema Validators

For YAML schemas (like kpaas configurations):

# Using yamllint with schema validation
# Configure your validator to use the $schema field in the YAML files

Contributing

1. Schema Updates: When updating schemas, ensure backward compatibility where possible
2. Documentation: Update this README when adding new schemas or making significant changes
3. Validation: Test schema changes against existing configurations
4. Versioning: Consider API versioning strategies for breaking changes

API Versions

• Runway API: runway.aa.com/v1alpha1
  • Used by KPaaS schemas (Conductor, WebApp)
  • Follows Kubernetes API conventions

References

• JSON Schema Specification
• Kubernetes API Conventions
• Ping Federate Documentation

Support

For questions about these schemas or to request changes, please contact the author.