Skip to content

GovOps: Schema Registry MVP

Jump to bottom
Michael Schwartz edited this page Nov 20, 2025 · 1 revision

Schema Registry Design - MVP Requirements

Overview

This document defines the detailed requirements for the Schema Registry system in Agama Lab. The Schema Registry enables users to define Protobuf schemas with rich metadata about entities and properties (claims), create parent schemas for reuse, and generate Cedar schemas from these definitions. This provides a bridge between Protobuf-based data validation and Cedar policy enforcement.

Background

The Schema Registry serves as a central repository for structured data definitions that:

  • Define Entity Types: Protobuf message types that represent entities (principals, resources, actions)
  • Capture Metadata: Rich metadata about properties/claims including validation rules, descriptions, and constraints
  • Support Inheritance: Parent schemas that can be extended by child schemas
  • Generate Cedar Schemas: Automatic conversion from Protobuf schema definitions to Cedar schema format
  • Enable Type Safety: Ensure policies reference valid entity types and attributes

Architecture

graph TB
    subgraph AgamaLab["Agama Lab Frontend"]
        SchemaRegistryUI[Schema Registry UI]
        SchemaEditor[Schema Editor]
        CedarSchemaEditor[Cedar Schema Editor]
        MetadataEditor[Metadata Editor]
    end
    
    subgraph AgamaAPI["Agama Lab API"]
        SchemaRegistryAPI[Schema Registry API]
        ProtobufValidator[Protobuf Validator]
        CedarSchemaGenerator[Cedar Schema Generator]
        MetadataManager[Metadata Manager]
    end
    
    subgraph Storage["Storage"]
        SchemaStore[Schema Store]
        MetadataStore[Metadata Store]
        GitHub[GitHub Repositories]
    end
    
    subgraph Tools["External Tools"]
        ProtobufCompiler[Protobuf Compiler]
        Protovalidate[Protovalidate]
    end
    
    SchemaRegistryUI --> SchemaRegistryAPI
    SchemaEditor --> SchemaRegistryAPI
    CedarSchemaEditor --> SchemaRegistryAPI
    MetadataEditor --> SchemaRegistryAPI
    
    SchemaRegistryAPI --> ProtobufValidator
    SchemaRegistryAPI --> CedarSchemaGenerator
    SchemaRegistryAPI --> MetadataManager
    
    ProtobufValidator --> ProtobufCompiler
    ProtobufValidator --> Protovalidate
    
    SchemaRegistryAPI --> SchemaStore
    MetadataManager --> MetadataStore
    SchemaRegistryAPI --> GitHub
    
    CedarSchemaGenerator --> SchemaStore
    CedarSchemaGenerator --> MetadataStore
    
    style SchemaRegistryUI fill:#e3f2fd
    style CedarSchemaGenerator fill:#fff4e1
    style Protovalidate fill:#e8f5e9
Loading

Core Concepts

Schema Definition

A Schema in the registry represents a collection of entity type definitions, typically organized by namespace. Each schema can:

  • Define multiple entity types (Protobuf messages)
  • Specify parent schema relationships
  • Include metadata about entities and properties
  • Generate Cedar schema output

Entity Type

An Entity Type corresponds to a Protobuf message type that represents a principal, resource, or action in Cedar. Entity types have:

  • Name: Unique identifier (e.g., User, Document, ReadAction)
  • Namespace: Organizational grouping (e.g., AcmeCorp::)
  • Shape: Attributes/properties that entities of this type can have
  • Membership: Parent entity types (for hierarchical relationships)
  • Metadata: Descriptions, validation rules, constraints

Property/Claim

A Property (also called a "claim" in JWT contexts) is an attribute of an entity type. Properties have:

  • Name: Attribute identifier
  • Type: Cedar type (String, Long, Bool, Set, Record, etc.)
  • Required/Optional: Whether the property must be present
  • Validation Rules: Constraints from Protovalidate annotations
  • Metadata: Description, examples, documentation

Parent Schema

A Parent Schema is a base schema that can be extended by other schemas. Child schemas inherit:

  • Entity type definitions
  • Property definitions
  • Validation rules
  • Metadata

This enables schema composition and reuse across different domains or applications.

Requirements

REQ-SCHEMA-001: Schema Definition and Management

User Story: As an AI_Developer, I want to define Protobuf schemas in Agama Lab, so that I can create structured data definitions for my policies.

Functional Requirements

  1. Schema Creation

    • THE Schema Registry SHALL provide a UI for creating new schemas
    • THE Schema Registry SHALL allow users to specify schema metadata (name, namespace, version, description)
    • THE Schema Registry SHALL support importing existing Protobuf .proto files
    • THE Schema Registry SHALL support creating schemas from scratch using a visual editor
    • THE Schema Registry SHALL validate Protobuf syntax in real-time

  2. Schema Storage

    • THE Schema Registry SHALL store schemas in GitHub repositories
    • THE Schema Registry SHALL organize schemas by namespace
    • THE Schema Registry SHALL support versioning of schemas
    • THE Schema Registry SHALL maintain schema history

  3. Schema Validation

    • THE Schema Registry SHALL validate Protobuf syntax using protoc
    • THE Schema Registry SHALL validate Protovalidate annotations
    • THE Schema Registry SHALL check for naming conflicts within namespaces
    • THE Schema Registry SHALL validate parent schema references

Technical Requirements

  • Schemas SHALL be stored as Protobuf .proto files
  • Schemas SHALL follow standard Protobuf package naming conventions
  • Schema validation SHALL use protoc compiler
  • Schema validation SHALL use protovalidate for annotation validation

Acceptance Criteria

  1. WHEN an AI_Developer creates a schema, THE system SHALL generate valid Protobuf syntax
  2. WHEN an AI_Developer imports a .proto file, THE system SHALL parse and validate it
  3. WHERE Protobuf syntax is invalid, THE system SHALL display specific error messages
  4. WHERE schema validation fails, THE system SHALL prevent saving

REQ-SCHEMA-002: Entity Type Definition

User Story: As an AI_Developer, I want to define entity types with their properties, so that I can specify the structure of principals and resources in my policies.

Functional Requirements

  1. Entity Type Creation

    • THE Schema Registry SHALL provide a UI for defining entity types
    • THE Schema Registry SHALL allow users to specify entity type name and namespace
    • THE Schema Registry SHALL support defining entity types as Protobuf messages
    • THE Schema Registry SHALL allow specifying entity type as principal, resource, or both

  2. Property Definition

    • THE Schema Registry SHALL allow users to define properties (fields) for entity types
    • THE Schema Registry SHALL support all Cedar primitive types (String, Long, Bool)
    • THE Schema Registry SHALL support Cedar complex types (Set, Record, Entity)
    • THE Schema Registry SHALL allow marking properties as required or optional
    • THE Schema Registry SHALL support nested record types

  3. Property Metadata

    • THE Schema Registry SHALL allow adding descriptions to properties
    • THE Schema Registry SHALL allow adding examples to properties
    • THE Schema Registry SHALL capture Protovalidate validation rules
    • THE Schema Registry SHALL support custom metadata tags

Technical Requirements

  • Entity types SHALL be defined as Protobuf message types
  • Properties SHALL map to Protobuf message fields
  • Property types SHALL map to Cedar types
  • Metadata SHALL be stored alongside schema definitions

Acceptance Criteria

  1. WHEN an AI_Developer defines an entity type, THE system SHALL create a valid Protobuf message
  2. WHEN an AI_Developer adds a property, THE system SHALL update the Protobuf message definition
  3. WHEN an AI_Developer specifies a property type, THE system SHALL validate Cedar type compatibility
  4. WHERE property definition is invalid, THE system SHALL display specific errors

REQ-SCHEMA-003: Metadata Capture for Entities and Properties

User Story: As an AI_Developer, I want to capture rich metadata about entities and properties, so that I can document validation rules, constraints, and usage guidelines.

Functional Requirements

  1. Entity Metadata

    • THE Schema Registry SHALL allow users to add descriptions to entity types
    • THE Schema Registry SHALL allow users to specify entity type documentation
    • THE Schema Registry SHALL capture entity type annotations
    • THE Schema Registry SHALL allow tagging entity types with categories

  2. Property Metadata (Claims)

    • THE Schema Registry SHALL capture property descriptions
    • THE Schema Registry SHALL capture property examples
    • THE Schema Registry SHALL capture Protovalidate validation rules
    • THE Schema Registry SHALL capture property constraints (min/max, patterns, etc.)
    • THE Schema Registry SHALL allow adding custom metadata to properties
    • THE Schema Registry SHALL support JWT claim mappings

  3. Validation Rule Metadata

    • THE Schema Registry SHALL capture standard validation rules (email, uuid, min, max, etc.)
    • THE Schema Registry SHALL capture CEL-based custom validation rules
    • THE Schema Registry SHALL display validation rules in human-readable format
    • THE Schema Registry SHALL allow editing validation rules

Technical Requirements

  • Metadata SHALL be stored in a structured format (JSON/YAML)
  • Metadata SHALL be linked to schema definitions
  • Protovalidate annotations SHALL be parsed and stored as metadata
  • Metadata SHALL be versioned alongside schemas

Acceptance Criteria

  1. WHEN an AI_Developer adds metadata to an entity, THE system SHALL store it with the schema
  2. WHEN an AI_Developer adds validation rules, THE system SHALL parse Protovalidate annotations
  3. WHEN an AI_Developer views an entity type, THE system SHALL display all metadata
  4. WHERE metadata format is invalid, THE system SHALL display error messages

REQ-SCHEMA-004: Parent Schema Definition and Inheritance

User Story: As an AI_Developer, I want to define parent schemas that can be extended, so that I can reuse common entity definitions across multiple schemas.

Functional Requirements

  1. Parent Schema Declaration

    • THE Schema Registry SHALL allow users to declare a schema as a parent schema
    • THE Schema Registry SHALL allow child schemas to reference parent schemas
    • THE Schema Registry SHALL support multiple levels of inheritance
    • THE Schema Registry SHALL validate parent schema references

  2. Inheritance Behavior

    • THE Schema Registry SHALL allow child schemas to inherit entity types from parents
    • THE Schema Registry SHALL allow child schemas to extend parent entity types
    • THE Schema Registry SHALL allow child schemas to add new entity types
    • THE Schema Registry SHALL support overriding parent entity type properties (with validation)

  3. Inheritance Validation

    • THE Schema Registry SHALL validate that parent schemas exist
    • THE Schema Registry SHALL detect circular inheritance
    • THE Schema Registry SHALL validate that overrides are compatible
    • THE Schema Registry SHALL check for conflicts in inherited definitions

Technical Requirements

  • Parent schemas SHALL be referenced by namespace and version
  • Inheritance SHALL use Protobuf import and extend mechanisms
  • Child schemas SHALL merge parent definitions with local definitions
  • Inheritance validation SHALL occur during schema compilation

Acceptance Criteria

  1. WHEN an AI_Developer creates a parent schema, THE system SHALL mark it as extendable
  2. WHEN an AI_Developer creates a child schema, THE system SHALL inherit parent definitions
  3. WHEN an AI_Developer extends a parent entity type, THE system SHALL merge definitions
  4. WHERE inheritance creates conflicts, THE system SHALL display specific errors

REQ-SCHEMA-005: Cedar Schema Generation

User Story: As an AI_Developer, I want to generate Cedar schemas from Protobuf schema definitions, so that I can use these schemas in Cedar policies.

Functional Requirements

  1. Cedar Schema Generation

    • THE Schema Registry SHALL generate Cedar schema format from Protobuf definitions
    • THE Schema Registry SHALL convert Protobuf message types to Cedar entity types
    • THE Schema Registry SHALL convert Protobuf fields to Cedar attributes
    • THE Schema Registry SHALL map Protobuf types to Cedar types
    • THE Schema Registry SHALL generate Cedar namespace declarations

  2. Type Mapping

    • THE Schema Registry SHALL map Protobuf string to Cedar String
    • THE Schema Registry SHALL map Protobuf int64, uint64, int32, uint32 to Cedar Long
    • THE Schema Registry SHALL map Protobuf bool to Cedar Bool
    • THE Schema Registry SHALL map Protobuf repeated to Cedar Set
    • THE Schema Registry SHALL map Protobuf nested messages to Cedar Record
    • THE Schema Registry SHALL handle optional fields as optional Cedar attributes

  3. Membership Relations

    • THE Schema Registry SHALL generate Cedar memberOf relations from Protobuf inheritance
    • THE Schema Registry SHALL preserve parent-child relationships in Cedar schema
    • THE Schema Registry SHALL generate proper namespace paths

  4. Validation Integration

    • THE Schema Registry SHALL include validation constraints in Cedar schema annotations
    • THE Schema Registry SHALL preserve metadata in Cedar schema comments
    • THE Schema Registry SHALL generate Cedar schema in both human-readable and JSON formats

Technical Requirements

  • Cedar schema generation SHALL follow Cedar schema specification
  • Generated schemas SHALL be valid Cedar schemas
  • Type mappings SHALL be configurable
  • Generated schemas SHALL be stored alongside Protobuf schemas

Acceptance Criteria

  1. WHEN an AI_Developer generates a Cedar schema, THE system SHALL produce valid Cedar syntax
  2. WHEN an AI_Developer views generated Cedar schema, THE system SHALL display it in readable format
  3. WHEN an AI_Developer uses generated schema in Cedar Schema Editor, THE system SHALL validate policies
  4. WHERE type mapping fails, THE system SHALL display specific errors

REQ-SCHEMA-006: Cedar Schema Editor Integration

User Story: As an AI_Developer, I want to use schema definitions in the Cedar Schema Editor, so that I can build Cedar schemas with type safety and validation.

Functional Requirements

  1. Schema Selection

    • THE Cedar Schema Editor SHALL allow users to select schemas from the registry
    • THE Cedar Schema Editor SHALL display available entity types from selected schemas
    • THE Cedar Schema Editor SHALL allow selecting multiple schemas
    • THE Cedar Schema Editor SHALL show parent schema relationships

  2. Entity Type Selection

    • THE Cedar Schema Editor SHALL allow users to select entity types from registry schemas
    • THE Cedar Schema Editor SHALL display entity type properties/attributes
    • THE Cedar Schema Editor SHALL show property types and constraints
    • THE Cedar Schema Editor SHALL allow filtering entity types by namespace

  3. Auto-completion and Validation

    • THE Cedar Schema Editor SHALL provide auto-completion for entity type names
    • THE Cedar Schema Editor SHALL provide auto-completion for property names
    • THE Cedar Schema Editor SHALL validate entity type references
    • THE Cedar Schema Editor SHALL validate property references
    • THE Cedar Schema Editor SHALL show type errors in real-time

  4. Schema Assembly

    • THE Cedar Schema Editor SHALL allow building Cedar schemas from registry definitions
    • THE Cedar Schema Editor SHALL allow adding custom entity types
    • THE Cedar Schema Editor SHALL allow combining multiple registry schemas
    • THE Cedar Schema Editor SHALL generate final Cedar schema output

Technical Requirements

  • Cedar Schema Editor SHALL query Schema Registry API for available schemas
  • Schema selection SHALL be cached for performance
  • Auto-completion SHALL use Language Server Protocol (LSP) or similar
  • Validation SHALL use Cedar schema validator

Acceptance Criteria

  1. WHEN an AI_Developer opens Cedar Schema Editor, THE system SHALL load available schemas
  2. WHEN an AI_Developer selects an entity type, THE system SHALL display its properties
  3. WHEN an AI_Developer types in Cedar Schema Editor, THE system SHALL provide auto-completion
  4. WHERE entity type reference is invalid, THE system SHALL highlight the error

Data Models

Schema Definition

schema:
  id: string (UUID)
  name: string
  namespace: string
  version: string
  description: string
  parent_schemas:
    - namespace: string
      version: string
  entity_types:
    - entity_type_id: string
  metadata:
    created_at: timestamp
    updated_at: timestamp
    created_by: string
    tags: [string]
  protobuf_content: string (Protobuf .proto file content)
  cedar_schema: string (Generated Cedar schema)

Entity Type Definition

entity_type:
  id: string (UUID)
  schema_id: string
  name: string
  namespace: string
  full_name: string (namespace::name)
  protobuf_message: string (Message name)
  entity_kind: enum (principal | resource | both)
  properties:
    - property_id: string
  parent_types: [string] (Entity type names)
  metadata:
    description: string
    documentation: string
    examples: [string]
    annotations: map<string, string>

Property/Claim Definition

property:
  id: string (UUID)
  entity_type_id: string
  name: string
  cedar_type: string (String | Long | Bool | Set<...> | Record | Entity)
  protobuf_type: string (string | int64 | bool | repeated ...)
  required: boolean
  validation_rules:
    - rule_type: string (email | uuid | min | max | pattern | cel)
      rule_value: any
      rule_message: string
  metadata:
    description: string
    examples: [any]
    jwt_claim: string (optional, for JWT claim mapping)
    documentation: string
    tags: [string]

Parent Schema Relationship

parent_schema:
  child_schema_id: string
  parent_schema_id: string
  inheritance_type: enum (full | selective)
  overrides:
    - entity_type_name: string
      property_overrides: [string]

API Endpoints

Schema Management

POST /api/v1/schemas
  - Create new schema
  - Body: Schema definition
  - Response: Created schema with UUID

GET /api/v1/schemas
  - List all schemas
  - Query params: namespace, version, parent
  - Response: List of schemas

GET /api/v1/schemas/{id}
  - Get schema by ID
  - Response: Full schema definition

PUT /api/v1/schemas/{id}
  - Update schema
  - Body: Updated schema definition
  - Response: Updated schema

DELETE /api/v1/schemas/{id}
  - Delete schema (soft delete)
  - Response: Deletion confirmation

POST /api/v1/schemas/{id}/import
  - Import Protobuf file
  - Body: Protobuf file content
  - Response: Parsed schema definition

GET /api/v1/schemas/{id}/cedar
  - Get generated Cedar schema
  - Query params: format (human | json)
  - Response: Cedar schema content

Entity Type Management

POST /api/v1/schemas/{schema_id}/entity-types
  - Create entity type in schema
  - Body: Entity type definition
  - Response: Created entity type

GET /api/v1/schemas/{schema_id}/entity-types
  - List entity types in schema
  - Response: List of entity types

GET /api/v1/entity-types/{id}
  - Get entity type by ID
  - Response: Full entity type definition

PUT /api/v1/entity-types/{id}
  - Update entity type
  - Body: Updated entity type
  - Response: Updated entity type

GET /api/v1/entity-types/{id}/properties
  - Get properties for entity type
  - Response: List of properties

Property Management

POST /api/v1/entity-types/{entity_type_id}/properties
  - Add property to entity type
  - Body: Property definition
  - Response: Created property

PUT /api/v1/properties/{id}
  - Update property
  - Body: Updated property
  - Response: Updated property

DELETE /api/v1/properties/{id}
  - Remove property
  - Response: Deletion confirmation

Metadata Management

PUT /api/v1/entity-types/{id}/metadata
  - Update entity type metadata
  - Body: Metadata object
  - Response: Updated metadata

PUT /api/v1/properties/{id}/metadata
  - Update property metadata
  - Body: Metadata object
  - Response: Updated metadata

GET /api/v1/entity-types/{id}/metadata
  - Get entity type metadata
  - Response: Metadata object

GET /api/v1/properties/{id}/metadata
  - Get property metadata
  - Response: Metadata object

Parent Schema Management

POST /api/v1/schemas/{id}/parents
  - Add parent schema reference
  - Body: Parent schema reference
  - Response: Added parent relationship

GET /api/v1/schemas/{id}/parents
  - Get parent schemas
  - Response: List of parent schemas

GET /api/v1/schemas/{id}/children
  - Get child schemas
  - Response: List of child schemas

DELETE /api/v1/schemas/{id}/parents/{parent_id}
  - Remove parent schema reference
  - Response: Deletion confirmation

Cedar Schema Generation

POST /api/v1/schemas/{id}/generate-cedar
  - Generate Cedar schema from Protobuf
  - Query params: format (human | json), include_metadata
  - Response: Generated Cedar schema

POST /api/v1/schemas/batch-generate-cedar
  - Generate Cedar schema from multiple schemas
  - Body: Array of schema IDs
  - Response: Combined Cedar schema

Schema Search and Discovery

GET /api/v1/schemas/search
  - Search schemas
  - Query params: q (search query), namespace, tags
  - Response: Matching schemas

GET /api/v1/entity-types/search
  - Search entity types across schemas
  - Query params: q, namespace, entity_kind
  - Response: Matching entity types

GET /api/v1/properties/search
  - Search properties across entity types
  - Query params: q, type, validation_rule
  - Response: Matching properties

Validation

POST /api/v1/schemas/{id}/validate
  - Validate Protobuf schema
  - Response: Validation results

POST /api/v1/schemas/{id}/validate-cedar
  - Validate generated Cedar schema
  - Response: Validation results

POST /api/v1/schemas/{id}/validate-inheritance
  - Validate parent schema inheritance
  - Response: Inheritance validation results

User Experience Features

Schema Editor UI

graph TB
    A[Schema Editor] --> B[Schema Metadata Panel]
    A --> C[Entity Types List]
    A --> D[Protobuf Editor]
    A --> E[Cedar Preview]
    A --> F[Parent Schema Selector]
    
    B --> B1[Name Input]
    B --> B2[Namespace Input]
    B --> B3[Version Input]
    B --> B4[Description Editor]
    
    C --> C1[Entity Type Card]
    C1 --> C2[Entity Name]
    C1 --> C3[Properties Count]
    C1 --> C4[Entity Kind Badge]
    
    D --> D1[Protobuf Syntax Editor]
    D1 --> D2[Syntax Highlighting]
    D1 --> D3[Auto-completion]
    D1 --> D4[Error Highlighting]
    
    E --> E1[Cedar Schema Preview]
    E1 --> E2[Human-readable Format]
    E1 --> E3[JSON Format Toggle]
    E1 --> E4[Copy to Clipboard]
    
    F --> F1[Parent Schema Dropdown]
    F --> F2[Inherited Entities Display]
    F --> F3[Override Options]
    
    style A fill:#e3f2fd
    style D fill:#263238,color:#fff
    style E fill:#fff4e1
Loading

Key UX Features

  1. Visual Schema Builder

    • Drag-and-drop interface for creating entity types
    • Visual property editor with type selectors
    • Real-time Protobuf preview
    • Real-time Cedar schema preview

  2. Metadata Editor

    • Rich text editor for descriptions
    • Form-based validation rule editor
    • Example value inputs with type validation
    • Tag management interface

  3. Parent Schema Browser

    • Tree view of parent-child relationships
    • Visual inheritance diagram
    • Conflict detection and resolution UI
    • Override management interface

  4. Cedar Schema Editor Integration

    • Schema selector dropdown in Cedar Schema Editor
    • Entity type browser panel
    • Property auto-completion
    • Real-time validation feedback

  5. Search and Discovery

    • Global search across all schemas
    • Filter by namespace, tags, entity kind
    • Quick preview of entity types
    • Usage tracking (which policies use which schemas)

  6. Import/Export

    • Import Protobuf files with drag-and-drop
    • Export schemas as Protobuf files
    • Export Cedar schemas in multiple formats
    • Bulk import/export operations

  7. Validation Feedback

    • Inline error highlighting in Protobuf editor
    • Error panel with detailed messages
    • Warning indicators for potential issues
    • Success indicators for valid schemas

  8. Version Management

    • Version history viewer
    • Diff view between versions
    • Rollback capability
    • Version comparison tool

Workflow: Creating a Schema with Parent

sequenceDiagram
    participant User
    participant SchemaEditor as Schema Editor UI
    participant SchemaAPI as Schema Registry API
    participant ProtobufValidator as Protobuf Validator
    participant CedarGenerator as Cedar Schema Generator
    participant GitHub as GitHub
    
    User->>SchemaEditor: Create New Schema
    SchemaEditor->>User: Show Schema Metadata Form
    User->>SchemaEditor: Enter Name, Namespace, Version
    User->>SchemaEditor: Select Parent Schema
    SchemaEditor->>SchemaAPI: Get Parent Schema
    SchemaAPI->>SchemaEditor: Return Parent Schema Definition
    SchemaEditor->>User: Display Inherited Entity Types
    
    User->>SchemaEditor: Define Entity Types
    SchemaEditor->>SchemaEditor: Add Properties to Entities
    User->>SchemaEditor: Add Metadata to Properties
    SchemaEditor->>SchemaAPI: Validate Schema
    SchemaAPI->>ProtobufValidator: Validate Protobuf Syntax
    ProtobufValidator->>SchemaAPI: Validation Results
    SchemaAPI->>SchemaEditor: Display Validation Status
    
    User->>SchemaEditor: Generate Cedar Schema
    SchemaEditor->>SchemaAPI: Request Cedar Generation
    SchemaAPI->>CedarGenerator: Generate Cedar Schema
    CedarGenerator->>SchemaAPI: Generated Cedar Schema
    SchemaAPI->>SchemaEditor: Display Cedar Preview
    
    User->>SchemaEditor: Save Schema
    SchemaEditor->>SchemaAPI: Save Schema Request
    SchemaAPI->>GitHub: Commit to Repository
    GitHub->>SchemaAPI: Commit Confirmation
    SchemaAPI->>SchemaEditor: Save Success
    SchemaEditor->>User: Show Success Message
Loading

Workflow: Using Schema in Cedar Schema Editor

sequenceDiagram
    participant User
    participant CedarEditor as Cedar Schema Editor
    participant SchemaAPI as Schema Registry API
    participant PolicyValidator as Policy Validator
    
    User->>CedarEditor: Open Cedar Schema Editor
    CedarEditor->>SchemaAPI: Fetch Available Schemas
    SchemaAPI->>CedarEditor: Return Schema List
    
    User->>CedarEditor: Select Schema from Registry
    CedarEditor->>SchemaAPI: Get Schema Entity Types
    SchemaAPI->>CedarEditor: Return Entity Types with Properties
    
    User->>CedarEditor: Type Entity Type Name
    CedarEditor->>CedarEditor: Auto-complete from Registry
    CedarEditor->>User: Show Entity Type Suggestions
    
    User->>CedarEditor: Select Entity Type
    CedarEditor->>CedarEditor: Insert Entity Definition
    CedarEditor->>CedarEditor: Show Available Properties
    
    User->>CedarEditor: Type Property Name
    CedarEditor->>CedarEditor: Auto-complete Properties
    CedarEditor->>User: Show Property Suggestions with Types
    
    User->>CedarEditor: Complete Schema Definition
    CedarEditor->>PolicyValidator: Validate Cedar Schema
    PolicyValidator->>CedarEditor: Validation Results
    CedarEditor->>User: Show Validation Status
Loading

Detailed UI Components

Schema List View

graph TB
    A[Schema List] --> B[Search Bar]
    A --> C[Filter Panel]
    A --> D[Schema Cards]
    
    B --> B1[Search Input]
    B --> B2[Search Button]
    
    C --> C1[Namespace Filter]
    C --> C2[Version Filter]
    C --> C3[Parent Schema Filter]
    C --> C4[Tags Filter]
    
    D --> D1[Schema Card]
    D1 --> D2[Schema Name]
    D1 --> D3[Namespace Badge]
    D1 --> D4[Version Badge]
    D1 --> D5[Entity Types Count]
    D1 --> D6[Parent Schemas Count]
    D1 --> D7[Actions: Edit, View, Delete]
    
    style D1 fill:#e3f2fd
Loading

Entity Type Editor

graph TB
    A[Entity Type Editor] --> B[Entity Metadata]
    A --> C[Properties List]
    A --> D[Property Editor]
    A --> E[Validation Rules]
    
    B --> B1[Name Input]
    B --> B2[Namespace Display]
    B --> B3[Entity Kind Selector]
    B --> B4[Description Editor]
    B --> B5[Parent Types Selector]
    
    C --> C1[Property Row]
    C1 --> C2[Property Name]
    C1 --> C3[Type Badge]
    C1 --> C4[Required Indicator]
    C1 --> C5[Actions: Edit, Delete]
    
    D --> D1[Property Name Input]
    D --> D2[Type Selector]
    D --> D3[Required Toggle]
    D --> D4[Default Value Input]
    D --> D5[Description Editor]
    
    E --> E1[Validation Rule List]
    E --> E2[Add Rule Button]
    E1 --> E3[Rule Type Selector]
    E1 --> E4[Rule Value Input]
    E1 --> E5[Rule Message Input]
    
    style A fill:#e3f2fd
    style D fill:#fff4e1
    style E fill:#e8f5e9
Loading

Parent Schema Selector

graph TB
    A[Parent Schema Selector] --> B[Schema Browser]
    A --> C[Inheritance Preview]
    A --> D[Conflict Resolution]
    
    B --> B1[Schema Tree View]
    B1 --> B2[Parent Schema Node]
    B2 --> B3[Entity Types]
    B3 --> B4[Properties]
    
    C --> C1[Inherited Entities List]
    C --> C2[Overridden Entities List]
    C --> C3[New Entities List]
    
    D --> D1[Conflict Detection]
    D1 --> D2[Conflict List]
    D2 --> D3[Resolution Options]
    D3 --> D4[Keep Parent]
    D3 --> D5[Override with Child]
    D3 --> D6[Custom Resolution]
    
    style A fill:#e3f2fd
    style D fill:#ffcdd2
Loading

Metadata Editor Panel

graph TB
    A[Metadata Editor] --> B[Description Tab]
    A --> C[Validation Rules Tab]
    A --> D[Examples Tab]
    A --> E[Documentation Tab]
    
    B --> B1[Rich Text Editor]
    B --> B2[Markdown Support]
    B --> B3[Preview Toggle]
    
    C --> C1[Rule Type Dropdown]
    C --> C2[Rule Configuration]
    C --> C3[Rule Preview]
    C --> C4[Add Custom CEL Rule]
    
    D --> D1[Example Value Input]
    D --> D2[Type Validator]
    D --> D3[Example List]
    D --> D4[Add Example Button]
    
    E --> E1[Documentation Editor]
    E --> E2[JWT Claim Mapping]
    E --> E3[Tags Input]
    E --> E4[Custom Annotations]
    
    style A fill:#fff4e1
    style C fill:#e8f5e9
Loading

Protovalidate Integration

Validation Rule Capture

The Schema Registry shall capture Protovalidate annotations and store them as metadata:

message User {
  string id = 1 [
    (buf.validate.field).string.uuid = true,
    (buf.validate.field).string.min_len = 1
  ];
  string email = 2 [
    (buf.validate.field).string.email = true
  ];
  uint32 age = 3 [
    (buf.validate.field).uint32.gte = 0,
    (buf.validate.field).uint32.lte = 150
  ];
  
  option (buf.validate.message).cel = {
    id: "age_requires_email"
    message: "Users over 13 must have email"
    expression: "this.age <= 13 || has(this.email)"
  };
}

These annotations shall be:

  • Parsed from Protobuf files
  • Stored as structured metadata
  • Displayed in the UI
  • Included in Cedar schema generation as annotations/comments

Cedar Schema Generation Details

Type Mapping Table

Protobuf Type Cedar Type Notes
string String Direct mapping
int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64 Long All integer types map to Long
bool Bool Direct mapping
bytes String Base64 encoded
repeated T Set<T> Repeated fields become sets
map<K, V> Record Maps become records (if K is string)
message M Record or Entity Nested messages become records or entity references
oneof Record with optional fields Oneof becomes optional record fields
optional T T? Optional fields become optional attributes

Example Generation

Protobuf Schema:

syntax = "proto3";

package acme.user.v1;

message User {
  string id = 1 [(buf.validate.field).string.uuid = true];
  string email = 2 [(buf.validate.field).string.email = true];
  uint32 age = 3 [(buf.validate.field).uint32.lte = 150];
  repeated string roles = 4;
}

message UserGroup {
  string id = 1;
  repeated User members = 2;
}

Generated Cedar Schema:

namespace AcmeUser {

// User entity type
// Description: Represents a user in the system
entity User in [UserGroup] {
  // UUID identifier
  // Validation: uuid format required
  id: String,
  
  // Email address
  // Validation: email format required
  email: String,
  
  // Age in years
  // Validation: must be <= 150
  age: Long,
  
  // User roles
  roles: Set<String>
}

// UserGroup entity type
entity UserGroup {
  id: String,
  members: Set<AcmeUser::User>
}

}

Error Handling

Validation Errors

  • Protobuf Syntax Errors: Display line number, column, and specific error message
  • Protovalidate Errors: Show which field has invalid annotation and what's wrong
  • Type Mapping Errors: Indicate which Protobuf type cannot be mapped to Cedar
  • Inheritance Errors: Show conflicts, circular dependencies, or missing parent schemas

User-Friendly Error Messages

  • Use plain language instead of technical jargon
  • Provide suggestions for fixing errors
  • Link to documentation for complex errors
  • Show error context (which entity type, which property)

Performance Requirements

  • Schema loading: < 1 second for typical schemas
  • Entity type search: < 500ms
  • Cedar schema generation: < 2 seconds for typical schemas
  • Auto-completion response: < 200ms
  • Validation: < 1 second for typical schemas

Security Requirements

  • Schemas SHALL be stored in user-accessible GitHub repositories
  • Access control SHALL be managed through GitHub permissions
  • Schema content SHALL not contain sensitive data
  • Metadata SHALL be sanitized before display

Testing Requirements

Unit Tests

  • Protobuf parsing and validation
  • Type mapping logic
  • Cedar schema generation
  • Metadata extraction
  • Inheritance resolution

Integration Tests

  • Schema Registry API endpoints
  • Cedar Schema Editor integration
  • GitHub integration
  • Protovalidate integration

Acceptance Tests

  • User can create schema with entity types
  • User can define parent schema relationships
  • User can generate Cedar schema
  • User can use schema in Cedar Schema Editor

Future Enhancements (Out of MVP Scope)

  1. Advanced Type System: Support for custom Cedar types, extension types
  2. Schema Templates: Pre-built schema templates for common use cases
  3. Schema Marketplace: Share and discover community schemas
  4. Automated Testing: Generate test cases from validation rules
  5. Schema Migration Tools: Automated migration between schema versions
  6. Multi-language Code Generation: Generate code from schemas (Go, Java, Python, etc.)
  7. Schema Analytics: Usage tracking, impact analysis for schema changes
  8. Collaborative Editing: Multi-user schema editing with conflict resolution

Dependencies

  • Protobuf compiler (protoc)
  • Protovalidate library
  • Cedar schema validator
  • GitHub API
  • Language Server Protocol (LSP) for auto-completion

References

Clone this wiki locally