Type Alias IJsonSchemaDescriptive

Descriptive type schema info with required documentation.

AutoBeOpenApi.IJsonSchemaDescriptive extends the base JSON schema types with a required description field for API documentation. For object types, it also includes an x-autobe-specification field for implementation guidance.

Type Construction Order

When constructing types, fields MUST be specified in this order:

1. x-autobe-specification → HOW to implement this type
2. description → WHAT for API consumers
3. Type metadata (type, properties, etc.) → WHAT technically

Two-Field Documentation Pattern

This type system separates concerns between two documentation fields:

• description: Standard OpenAPI field for API consumers. Displayed in Swagger UI, SDK docs, etc. Focuses on WHAT and WHY.
• x-autobe-specification: AutoBE-internal field for implementation agents. Focuses on HOW to implement.

Guidelines for description

• Reference the corresponding database schema documentation
• Organize into multiple paragraphs for complex types
• Focus on business meaning, relationships, and constraints
• Keep accessible to API consumers (no implementation details)

Guidelines for x-autobe-specification (Object Types)

• Provide precise implementation instructions
• Include source tables, join conditions, aggregation formulas
• Document edge cases and business rules
• Must be detailed enough for Realize Agent to implement