feat(reconcile): add a MetaSchema kind for declarative metaschema management

cmd/reconcile.go

@@ -25,11 +25,12 @@ func ReconcileCommand(cliConfig *Config) *cli.Command {
 			Kinds: PlatformUser (platform admins and members), Permission (custom
 			permissions), Role (platform-level roles), Preference (platform
 			settings), Webhook (webhook endpoints), BillingProduct (billing products
-			and their prices), and BillingPlan (billing plans and the products they
-			bundle). Deleting a permission, a custom role, or a webhook needs an
-			explicit 'delete: true' on its entry; nothing is deleted by omission, a
-			predefined role cannot be deleted, and a product or plan cannot be deleted
-			through the API. A preference left out of the file resets to its default.
+			and their prices), BillingPlan (billing plans and the products they
+			bundle), and MetaSchema (metadata validation schemas). Deleting a
+			permission, a custom role, or a webhook needs an explicit 'delete: true'
+			on its entry; nothing is deleted by omission, a predefined role cannot be
+			deleted, and a product or plan cannot be deleted through the API. A
+			preference left out of the file resets to its default.
 			Log in as a superuser (for example the bootstrap service account) with
 			--header.
 
@@ -94,6 +95,7 @@ func buildReconcileRegistry(host, header string) (map[string]reconcile.Reconcile
 		reconcile.KindWebhook:        reconcile.NewWebhookReconciler(adminClient, header),
 		reconcile.KindBillingProduct: reconcile.NewBillingProductReconciler(api, header),
 		reconcile.KindBillingPlan:    reconcile.NewBillingPlanReconciler(api, header),
+		reconcile.KindMetaSchema:     reconcile.NewMetaSchemaReconciler(api, header),
 	}, nil
 }
 

core/metaschema/defaults.go

@@ -0,0 +1,39 @@
+package metaschema
+
+import _ "embed"
+
+// Built-in metaschema names. These are the schemas the server validates entity
+// metadata against, and the set the MetaSchema reconcile kind manages.
+const (
+	NameUser     = "user"
+	NameGroup    = "group"
+	NameOrg      = "organization"
+	NameRole     = "role"
+	NameProspect = "prospect"
+)
+
+//go:embed metaschemas/user.json
+var defaultUser []byte
+
+//go:embed metaschemas/group.json
+var defaultGroup []byte
+
+//go:embed metaschemas/org.json
+var defaultOrg []byte
+
+//go:embed metaschemas/role.json
+var defaultRole []byte
+
+//go:embed metaschemas/prospect.json
+var defaultProspect []byte
+
+// Defaults maps each built-in metaschema name to its shipped JSON schema. It is
+// the one source for both the server seeding (MigrateDefaults) and the MetaSchema
+// reconcile kind, so adding a metaschema for a new resource is a single edit here.
+var Defaults = map[string]string{
+	NameUser:     string(defaultUser),
+	NameGroup:    string(defaultGroup),
+	NameOrg:      string(defaultOrg),
+	NameRole:     string(defaultRole),
+	NameProspect: string(defaultProspect),
+}

core/metaschema/defaults_test.go

@@ -0,0 +1,27 @@
+package metaschema
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestDefaults(t *testing.T) {
+	want := []string{NameUser, NameGroup, NameOrg, NameRole, NameProspect}
+	if len(Defaults) != len(want) {
+		t.Fatalf("Defaults has %d entries, want %d", len(Defaults), len(want))
+	}
+	for _, name := range want {
+		schema, ok := Defaults[name]
+		if !ok {
+			t.Errorf("Defaults is missing %q", name)
+			continue
+		}
+		if schema == "" {
+			t.Errorf("Defaults[%q] is empty", name)
+		}
+		var v any
+		if err := json.Unmarshal([]byte(schema), &v); err != nil {
+			t.Errorf("Defaults[%q] is not valid JSON: %v", name, err)
+		}
+	}
+}

docs/content/docs/reconcile.mdx

@@ -358,6 +358,31 @@ spec:
   timestamps, and metadata are server-owned or out of scope and not written; out-of-scope
   plans are left out too.
 
+## The MetaSchema kind
+
+`MetaSchema` manages the JSON schemas that validate the `metadata` field on the
+built-in entities: user, group, organization, role, and prospect. Each is a
+value: the file sets its schema, and one left out resets to the shipped default.
+There is no delete flag, and a name outside the built-in set is rejected.
+
+```yaml
+apiVersion: v1
+kind: MetaSchema
+spec:
+  - name: organization
+    schema: |
+      {
+        "type": "object",
+        "properties": { "cost_center": { "type": "string" } },
+        "required": ["cost_center"]
+      }
+```
+
+The schema is a JSON string. Export writes only the built-ins whose schema differs
+from the default, so a freshly exported file lists just what an operator changed.
+
+A metaschema change reaches every pod within the server's cache refresh interval, about a minute by default, so it can take that long to take effect everywhere.
+
 ## Running it
 
 Log in as a superuser. The bootstrap service user exists for exactly this; its client id
@@ -401,7 +426,7 @@ The kind argument is case-insensitive and accepts a plural, so `platformuser` an
 ## More kinds
 
 This page covers `PlatformUser`, `Permission`, `Role`, `Preference`, `Webhook`,
-`BillingProduct`, and `BillingPlan`. The design and
+`BillingProduct`, `BillingPlan`, and `MetaSchema`. The design and
 the rules every kind follows live in
 [RFC 0001](https://github.com/raystack/frontier/blob/main/docs/rfcs/0001-declarative-reconcile.md),
 which also lists the kinds proposed next. The flag reference for both commands is in the

docs/rfcs/0001-declarative-reconcile.md

@@ -56,6 +56,7 @@ role is a value.
 | Role, predefined | value | name | reset to the shipped definition | cannot be removed |
 | Preference | value | trait name | reset to the trait default | leave the entry out, it resets |
 | Webhook | object | URL | plan fails | set `delete: true` |
+| MetaSchema | value | name | reset to the shipped schema | leave the entry out, it resets |
 
 Every kind, current and future, follows the same five rules:
 
@@ -229,6 +230,12 @@ identity. An empty event set means all events, which is the server default. The
 is server-owned: the server makes it on create and never returns it, so it is never in the
 file, a plan, or an export.
 
+**MetaSchema.** An entry is `{name, schema}`. The name is one of the built-in
+schemas the server validates entity metadata against: user, group, organization,
+role, and prospect. Each is a value whose default is the shipped schema. The file
+sets a schema; a built-in left out resets to its default. There is no delete flag,
+and a name outside the built-in set is rejected. The schema is a JSON string.
+
 ## Server-side changes
 
 Two boot behaviors changed to make this flow work.
@@ -278,7 +285,6 @@ roles, committed as the desired-state files, then dropping the setting from the
 - A read-only API that returns the server's own predefined-role definitions, so the reset target
   comes from the running server instead of the CLI's compiled copy. This removes the
   image-version coupling.
-- Metaschemas as a kind, once the server stops caching them per pod at boot.
 - Passing the auth token without putting it in the process arguments.
 - Billing plans as a kind, replacing the boot-time plans loader.
 - Removing relation-based ownership from the base schema, so narrowing a predefined role

internal/reconcile/metaschema.go

@@ -0,0 +1,209 @@
+package reconcile
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+)
+
+// KindMetaSchema is the desired-state document kind for entity metaschemas.
+const KindMetaSchema = "MetaSchema"
+
+// MetaSchemaSpec is one desired metaschema. Name is a built-in metaschema name
+// the server knows; Schema is the JSON schema as a string.
+type MetaSchemaSpec struct {
+	Name   string `yaml:"name"`
+	Schema string `yaml:"schema"`
+}
+
+// currentMetaSchema is a metaschema as it exists on the server.
+type currentMetaSchema struct {
+	ID     string
+	Name   string
+	Schema string
+}
+
+// metaSchemaOp is a single planned change. schema is the JSON to write; id is the
+// server id for an update, empty when the metaschema must be created. fromDefault
+// marks a reset, so the plan can say so.
+type metaSchemaOp struct {
+	name        string
+	id          string
+	schema      string
+	fromDefault bool
+}
+
+func (o metaSchemaOp) String() string {
+	switch {
+	case o.id == "":
+		return fmt.Sprintf("create metaschema %s", o.name)
+	case o.fromDefault:
+		return fmt.Sprintf("reset metaschema %s to default", o.name)
+	default:
+		return fmt.Sprintf("set metaschema %s", o.name)
+	}
+}
+
+// decodeJSON parses a single JSON value, preserving number literals so a large
+// or high-precision number is not rounded through float64. It rejects trailing
+// data after the value, matching a strict single-document parse.
+func decodeJSON(s string) (any, error) {
+	dec := json.NewDecoder(strings.NewReader(s))
+	dec.UseNumber()
+	var v any
+	if err := dec.Decode(&v); err != nil {
+		return nil, err
+	}
+	if _, err := dec.Token(); err != io.EOF {
+		return nil, fmt.Errorf("unexpected trailing data after JSON value")
+	}
+	return v, nil
+}
+
+// canonicalJSON returns a stable form of a JSON document, so two schemas that
+// differ only in whitespace or key order compare equal, while a real difference
+// in a number is kept (numbers are compared by their literal, not by float64).
+// It keeps the export round-trip stable and stops formatting from making a false
+// diff.
+func canonicalJSON(s string) (string, error) {
+	v, err := decodeJSON(s)
+	if err != nil {
+		return "", err
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+// validateSchemaDocument checks the string is a JSON object, not just any valid
+// JSON. A non-object root (a number, string, boolean, or array) parses as JSON
+// but is not a usable metadata schema: the server compiles it with gojsonschema
+// for every entity of that type, and a non-object root errors there, which would
+// start failing all metadata writes for that entity. Catching it here keeps the
+// whole file from partially applying.
+func validateSchemaDocument(schema string) error {
+	root, err := decodeJSON(schema)
+	if err != nil {
+		return fmt.Errorf("schema is not valid JSON: %w", err)
+	}
+	if _, ok := root.(map[string]any); !ok {
+		return fmt.Errorf("schema must be a JSON object")
+	}
+	return nil
+}
+
+// validateMetaSchemaSpecs checks every entry without touching the server: the
+// name is a known built-in, no name repeats, and the schema is a non-empty JSON
+// object. defaults is the managed set and the source of known names. Names are
+// matched case-insensitively, matching the sibling kinds, so `Organization` and
+// `organization` both name the same built-in.
+func validateMetaSchemaSpecs(specs []MetaSchemaSpec, defaults map[string]string) error {
+	seen := map[string]struct{}{}
+	for _, s := range specs {
+		name := strings.ToLower(strings.TrimSpace(s.Name))
+		if name == "" {
+			return fmt.Errorf("metaschema name is required")
+		}
+		if _, ok := defaults[name]; !ok {
+			return fmt.Errorf("unknown metaschema %q", s.Name)
+		}
+		if _, dup := seen[name]; dup {
+			return fmt.Errorf("metaschema %q is listed more than once", name)
+		}
+		seen[name] = struct{}{}
+		if strings.TrimSpace(s.Schema) == "" {
+			return fmt.Errorf("metaschema %q: schema is required", name)
+		}
+		if err := validateSchemaDocument(s.Schema); err != nil {
+			return fmt.Errorf("metaschema %q: %w", name, err)
+		}
+	}
+	return nil
+}
+
+// diffMetaSchemas returns the ops that make the server's built-in metaschemas
+// match the desired spec. The file is the full desired state: a built-in the file
+// lists is set to its schema, and a built-in the file leaves out is reset to its
+// shipped default. defaults is the managed set: its keys are the built-ins, its
+// values the reset targets.
+func diffMetaSchemas(desired []MetaSchemaSpec, current []currentMetaSchema, defaults map[string]string) ([]metaSchemaOp, error) {
+	desiredByName := make(map[string]string, len(desired))
+	for _, s := range desired {
+		desiredByName[strings.ToLower(strings.TrimSpace(s.Name))] = s.Schema
+	}
+	currentByName := make(map[string]currentMetaSchema, len(current))
+	for _, c := range current {
+		currentByName[c.Name] = c
+	}
+
+	names := make([]string, 0, len(defaults))
+	for name := range defaults {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	var ops []metaSchemaOp
+	for _, name := range names {
+		want, inFile := desiredByName[name]
+		if !inFile {
+			want = defaults[name]
+		}
+		wantCanon, err := canonicalJSON(want)
+		if err != nil {
+			return nil, fmt.Errorf("metaschema %q: schema is not valid JSON: %w", name, err)
+		}
+
+		cur, exists := currentByName[name]
+		if exists {
+			if curCanon, err := canonicalJSON(cur.Schema); err == nil && curCanon == wantCanon {
+				continue
+			}
+		}
+		ops = append(ops, metaSchemaOp{
+			name:        name,
+			id:          cur.ID, // empty when the metaschema is not on the server
+			schema:      want,
+			fromDefault: !inFile,
+		})
+	}
+	return ops, nil
+}
+
+// exportMetaSchemas returns the built-ins whose current schema differs from the
+// default, sorted by name, as a desired-state spec. A built-in at its default is
+// omitted, so reconciling an export plans no changes.
+func exportMetaSchemas(current []currentMetaSchema, defaults map[string]string) ([]MetaSchemaSpec, error) {
+	byName := make(map[string]currentMetaSchema, len(current))
+	for _, c := range current {
+		byName[c.Name] = c
+	}
+	names := make([]string, 0, len(defaults))
+	for name := range defaults {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	var specs []MetaSchemaSpec
+	for _, name := range names {
+		cur, exists := byName[name]
+		if !exists {
+			continue
+		}
+		curCanon, err := canonicalJSON(cur.Schema)
+		if err != nil {
+			// A stored schema that is not valid JSON still round-trips as its own
+			// literal, so emit it rather than dropping it.
+			specs = append(specs, MetaSchemaSpec{Name: name, Schema: cur.Schema})
+			continue
+		}
+		if defCanon, err := canonicalJSON(defaults[name]); err == nil && defCanon == curCanon {
+			continue
+		}
+		specs = append(specs, MetaSchemaSpec{Name: name, Schema: cur.Schema})
+	}
+	return specs, nil
+}