feat(schema): reserve validations key in schema spec v0.1.0

Reserves the top-level `validations:` key in schema spec v0.1.0 — proto, DB, YAML parser, lint, storage round-trip — without shipping the CEL engine. The engine and runtime evaluation land in Phase 2 (#76).

Wire format mirrors Kubernetes CRD x-kubernetes-validations and buf/protovalidate per the cel-validation design brief: each rule carries a path prefix, the CEL expression source, a human-readable failure message, an optional severity hint (error / warning), and an optional machine-readable reason code.

v0.1.0 lint at ImportSchema is structural only — rule and message required, severity optional and constrained to error / warning, x-* extension keys accepted. CEL compilation, field-reference resolution, and contradiction detection all defer to Phase 2 once the engine ships.

Why now: spec v0.1.0 freezes the meta-schema. Reserving the key now costs ~50 lines of plumbing; adding it later is a breaking spec bump that downstream tooling has to handle. Schema authors who want cross-field rules today can write CEL expressions; ImportSchema accepts and persists them, and they become no-ops at write time until Phase 2.

Closes #192. Final Phase-1 subtask of the cross-field validation umbrella (#76); pairs with #193 (dependentRequired) and #194 (prefix-overlap lint), both already in main.

Author: zeevdr

api/centralconfig/v1/types.pb.go

@@ -34,6 +34,10 @@ CREATE TABLE schema_versions (
     -- JSON array of {trigger_field, dependent_fields} entries encoding the
     -- schema's dependentRequired rules. Empty array when no rules exist.
     dependent_required JSONB NOT NULL DEFAULT '[]',
+    -- JSON array of {path, rule, message, severity?, reason?} entries
+    -- encoding the schema's CEL validation rules. Reserved in v0.1.0 —
+    -- parser persists; runtime engine ships in Phase 2 (see issue #76).
+    validations        JSONB NOT NULL DEFAULT '[]',
     created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
     UNIQUE(schema_id, version)
 );

cmd/server/openapi.json

@@ -18,8 +18,8 @@ LIMIT $1 OFFSET $2;
 DELETE FROM schemas WHERE id = $1;
 
 -- name: CreateSchemaVersion :one
-INSERT INTO schema_versions (schema_id, version, parent_version, description, checksum, dependent_required)
-VALUES ($1, $2, $3, $4, $5, $6)
+INSERT INTO schema_versions (schema_id, version, parent_version, description, checksum, dependent_required, validations)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
 RETURNING *;
 
 -- name: GetSchemaVersion :one

db/migrations/001_initial_schema.sql

@@ -23,6 +23,7 @@
     - [Tenant](#centralconfig-v1-Tenant)
     - [TypedValue](#centralconfig-v1-TypedValue)
     - [UsageStats](#centralconfig-v1-UsageStats)
+    - [ValidationRule](#centralconfig-v1-ValidationRule)
 
     - [FieldType](#centralconfig-v1-FieldType)
 
@@ -344,6 +345,7 @@ Each schema is versioned — updates create new immutable versions.
 | created_at | [google.protobuf.Timestamp](#google-protobuf-Timestamp) |  | When this version was created. |
 | info | [SchemaInfo](#centralconfig-v1-SchemaInfo) |  | Optional schema metadata: ownership, contact, labels. |
 | dependent_required | [DependentRequiredEntry](#centralconfig-v1-DependentRequiredEntry) | repeated | Cross-field "B required when A present" rules. Each entry declares one trigger field whose presence (non-null value) makes a list of dependent field paths required (also non-null). Equivalent to JSON Schema 2020-12 dependentRequired, scoped to schema-level cross-field requirement. Lint-checked at ImportSchema time (every path must reference a real field; trigger may not appear in its own dependents). Enforced at every config write against the post-merge snapshot. |
+| validations | [ValidationRule](#centralconfig-v1-ValidationRule) | repeated | Cross-field rule expressions reserved for future Common Expression Language (CEL) evaluation. Stored on the schema and round-tripped through ImportSchema/GetSchema; the runtime engine ships separately (see issue #76). Reserving the key in v0.1.0 of the schema spec avoids a breaking meta-schema change later. |
 
 
 
@@ -515,6 +517,33 @@ UsageStats represents aggregated read usage statistics for a config field.
 
 
 
+
+<a name="centralconfig-v1-ValidationRule"></a>
+
+### ValidationRule
+ValidationRule encodes one cross-field rule expressed in Common
+Expression Language (CEL). Reserved in v0.1.0 of the schema spec — the
+parser accepts and persists rules, but the engine that compiles and
+evaluates them ships separately (see issue #76 / .agents/context/cel-validation.md).
+
+Rules are scoped to a path prefix: an empty path means a schema-wide
+rule; a non-empty path anchors the rule to a group for documentation
+and UI grouping (the binding namespace itself always exposes every
+field via `self`, regardless of path).
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| path | [string](#string) |  | Optional path prefix scoping the rule to a group of fields. Empty string means the rule applies at schema scope. |
+| rule | [string](#string) |  | The CEL expression source. Lint at ImportSchema in v0.1.0 only checks that the string is non-empty; CEL compilation happens in Phase 2 once the engine ships. |
+| message | [string](#string) |  | Human-readable failure message shown to clients when the rule rejects a write. Required. |
+| severity | [string](#string) |  | Optional severity hint. Reserved values: &#34;error&#34; (default — write rejected) and &#34;warning&#34; (write accepted, surfaced for UI). v0.1.0 only validates the value is empty or one of the reserved set; the warning path is not yet enforced. |
+| reason | [string](#string) |  | Optional machine-readable failure code for SDK consumers that want to branch on rule outcome without parsing the message text. |
+
+
+
+
+
 
 
 

db/queries/schemas.sql

@@ -41,6 +41,9 @@ func schemaToProto(s domain.Schema, v domain.SchemaVersion, fields []domain.Sche
 	if entries := UnmarshalDependentRequired(v.DependentRequired); len(entries) > 0 {
 		result.DependentRequired = entries
 	}
+	if rules := UnmarshalValidations(v.Validations); len(rules) > 0 {
+		result.Validations = rules
+	}
 	return result
 }
 

docs/api/api-reference.md

@@ -616,6 +616,11 @@ func (s *Service) ImportSchema(ctx context.Context, req *pb.ImportSchemaRequest)
 	if err != nil {
 		return nil, status.Errorf(codes.Internal, "failed to encode dependentRequired: %v", err)
 	}
+	validations := yamlToProtoValidations(doc.Validations)
+	validationsJSON, err := MarshalValidations(validations)
+	if err != nil {
+		return nil, status.Errorf(codes.Internal, "failed to encode validations: %v", err)
+	}
 	checksum := computeChecksum(fields)
 
 	// Check if schema already exists by name.
@@ -626,7 +631,7 @@ func (s *Service) ImportSchema(ctx context.Context, req *pb.ImportSchemaRequest)
 
 	if errors.Is(err, domain.ErrNotFound) {
 		// New schema — create with v1.
-		resp, err := s.importCreateNew(ctx, doc, fields, checksum, depReqJSON)
+		resp, err := s.importCreateNew(ctx, doc, fields, checksum, depReqJSON, validationsJSON)
 		if err != nil || !req.AutoPublish {
 			return resp, err
 		}
@@ -651,14 +656,14 @@ func (s *Service) ImportSchema(ctx context.Context, req *pb.ImportSchemaRequest)
 	}
 
 	// Create new version.
-	resp, err := s.importNewVersion(ctx, existing, latestVersion, doc, fields, checksum, depReqJSON)
+	resp, err := s.importNewVersion(ctx, existing, latestVersion, doc, fields, checksum, depReqJSON, validationsJSON)
 	if err != nil || !req.AutoPublish {
 		return resp, err
 	}
 	return s.autoPublish(ctx, resp)
 }
 
-func (s *Service) importCreateNew(ctx context.Context, doc *SchemaYAML, fields []*pb.SchemaField, checksum string, depReqJSON []byte) (*pb.ImportSchemaResponse, error) {
+func (s *Service) importCreateNew(ctx context.Context, doc *SchemaYAML, fields []*pb.SchemaField, checksum string, depReqJSON, validationsJSON []byte) (*pb.ImportSchemaResponse, error) {
 	schema, err := s.store.CreateSchema(ctx, CreateSchemaParams{
 		Name:        doc.Name,
 		Description: ptrString(doc.Description),
@@ -674,6 +679,7 @@ func (s *Service) importCreateNew(ctx context.Context, doc *SchemaYAML, fields [
 		Description:       ptrString(doc.VersionDescription),
 		Checksum:          checksum,
 		DependentRequired: depReqJSON,
+		Validations:       validationsJSON,
 	})
 	if err != nil {
 		s.logger.ErrorContext(ctx, "import: create version", "error", err)
@@ -690,14 +696,15 @@ func (s *Service) importCreateNew(ctx context.Context, doc *SchemaYAML, fields [
 	}, nil
 }
 
-func (s *Service) importNewVersion(ctx context.Context, schema domain.Schema, latestVersion domain.SchemaVersion, doc *SchemaYAML, fields []*pb.SchemaField, checksum string, depReqJSON []byte) (*pb.ImportSchemaResponse, error) {
+func (s *Service) importNewVersion(ctx context.Context, schema domain.Schema, latestVersion domain.SchemaVersion, doc *SchemaYAML, fields []*pb.SchemaField, checksum string, depReqJSON, validationsJSON []byte) (*pb.ImportSchemaResponse, error) {
 	newVersion, err := s.store.CreateSchemaVersion(ctx, CreateSchemaVersionParams{
 		SchemaID:          schema.ID,
 		Version:           latestVersion.Version + 1,
 		ParentVersion:     &latestVersion.Version,
 		Description:       ptrString(doc.VersionDescription),
 		Checksum:          checksum,
 		DependentRequired: depReqJSON,
+		Validations:       validationsJSON,
 	})
 	if err != nil {
 		s.logger.ErrorContext(ctx, "import: create new version", "error", err)

docs/api/openapi.swagger.json

@@ -23,6 +23,9 @@ type CreateSchemaVersionParams struct {
 	// Pass an empty []byte (or nil) when no rules exist; the store will
 	// persist `[]` so reads always return well-formed JSON.
 	DependentRequired []byte
+	// Validations is the JSON-encoded list of CEL validation rules
+	// reserved in v0.1.0. Same nil-safe semantics as DependentRequired.
+	Validations []byte
 }
 
 // GetSchemaVersionParams identifies a specific schema version.

internal/schema/convert.go

@@ -145,6 +145,10 @@ func (m *MemoryStore) CreateSchemaVersion(_ context.Context, arg CreateSchemaVer
 	if len(depReq) == 0 {
 		depReq = []byte("[]")
 	}
+	validations := arg.Validations
+	if len(validations) == 0 {
+		validations = []byte("[]")
+	}
 	sv := domain.SchemaVersion{
 		ID:                m.nextID(),
 		SchemaID:          arg.SchemaID,
@@ -154,6 +158,7 @@ func (m *MemoryStore) CreateSchemaVersion(_ context.Context, arg CreateSchemaVer
 		Checksum:          arg.Checksum,
 		Published:         false,
 		DependentRequired: depReq,
+		Validations:       validations,
 		CreatedAt:         time.Now(),
 	}
 	m.schemaVersions[sv.ID] = sv