schema

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package schema defines the gt semantic schema model: declared types, fields, refs, references, and the validation/evolution rules that turn a plugin's schema declaration into a contract the host can enforce.

The package is a leaf: it must NOT import contract or the SDK root, because contract imports schema (see contract/gen/gen_vocabulary: the semantic vocabulary SSOT is codegen'd into vocabulary_gen.go so schema never reads the YAML at runtime). Keeping schema dependency-free is what prevents the contract -> schema -> contract import cycle.

Code generated by contract/gen/gen_vocabulary.go from contract/specs/schema.yaml. DO NOT EDIT.

Index

Constants

View Source
const (
	// SeverityError 表示契约违反(应阻断)。
	SeverityError = "error"
	// SeverityWarn 表示诊断/软降级。
	SeverityWarn = "warn"
)

Variables

This section is empty.

Functions

func IsBuiltinSemantic

func IsBuiltinSemantic(s Semantic) bool

IsBuiltinSemantic reports whether s is a platform-closed semantic.

Types

type Change

type Change struct {
	Kind string
	Path string
}

Change describes a single field-level difference between two same-id schemas. Kind corresponds to a key in evolutionCompatibility.

func Diff

func Diff(old, new *Schema) []Change

Diff computes the field-level differences between two same-id schemas.

type Entity

type Entity struct {
	Type string `yaml:"type"`
}

Entity 描述语义层的实体类型(领域自定,非平台枚举)。 仅当 semantic 为 entity_id / entity_name 时允许出现。

type EnumLiteral

type EnumLiteral struct {
	Str *string
	Int *int64
}

EnumLiteral 是 enum 字面量,支持字符串或整数两种形态。

func (EnumLiteral) Match

func (e EnumLiteral) Match(v event.Value) bool

Match 判断该字面量是否与给定 payload 标量值匹配(kind 一致且值相等)。

func (*EnumLiteral) UnmarshalYAML

func (e *EnumLiteral) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML 支持标量字符串或整数字面量。

type Field

type Field struct {
	Type        Type   `yaml:"type"`
	Description string `yaml:"description,omitempty"`
	Optional    bool   `yaml:"optional,omitempty"`

	// 语义层
	Semantic  Semantic      `yaml:"semantic,omitempty"`
	Unit      string        `yaml:"unit,omitempty"`
	Entity    *Entity       `yaml:"entity,omitempty"`
	Enum      []EnumLiteral `yaml:"enum,omitempty"`
	EnumOpen  bool          `yaml:"enum_open,omitempty"`
	Reference *Reference    `yaml:"reference,omitempty"`

	// 复合类型
	Items   *Field            `yaml:"items,omitempty"`
	Fields  map[string]*Field `yaml:"fields,omitempty"`
	Dynamic bool              `yaml:"dynamic,omitempty"`
	Key     *KeySpec          `yaml:"key,omitempty"`
	Values  *Field            `yaml:"values,omitempty"`

	// 查询能力
	Queryable    bool   `yaml:"queryable,omitempty"`
	Aggregatable bool   `yaml:"aggregatable,omitempty"`
	Groupable    bool   `yaml:"groupable,omitempty"`
	Alias        string `yaml:"alias,omitempty"`

	// 治理
	Sensitive  bool   `yaml:"sensitive,omitempty"`
	Deprecated bool   `yaml:"deprecated,omitempty"`
	ReplacedBy string `yaml:"replaced_by,omitempty"`
}

Field 是 schema 中的一个字段声明(§8.2)。

type IndexableField

type IndexableField struct {
	Path  string `yaml:"path"`
	Type  string `yaml:"type"`
	Alias string `yaml:"alias"`
}

IndexableField 是 v1 遗留的 indexable_fields 声明(AGENTS.md 最小 manifest)。 加载到 Manifest 时升格为对应 Field 的 Queryable + Alias。

type Issue

type Issue struct {
	RuleID   string // §8.6 规则 ID
	Path     string // 定位,如 schemas[0].fields.hp / hp
	Message  string
	Severity string // SeverityError | SeverityWarn
}

Issue 是 schema 层校验发现的一条问题。 与 contract.Violation 解耦:schema 包不依赖 contract,由上层 checker 转换为 Violation。

func CheckEvolution

func CheckEvolution(old, new *Schema) []Issue

CheckEvolution maps Diff results against the §8.5 matrix into issues: any change requiring a major bump -> error (gt.schema.breaking-change); backward-compatible-but-warned -> warn; benign -> no issue.

type KeySpec

type KeySpec struct {
	Semantic Semantic `yaml:"semantic"`
	Entity   *Entity  `yaml:"entity,omitempty"`
	Pattern  string   `yaml:"pattern,omitempty"`
}

KeySpec 描述 dynamic object 的键约束(§8.1)。

type Ref

type Ref struct {
	ID      string `yaml:"id" json:"id"`
	Version int    `yaml:"version" json:"version"`
}

Ref 标识一个 schema 的 (id, version) 对(§8.2)。 id 不带版本(如 game.player),version 是 major(如 1)。 线上形态为 id + ".v" + version(如 game.player.v1),由 Wire() 生成、ParseRef 解析。

func ParseRef

func ParseRef(wire string) (Ref, error)

ParseRef 把线上串 "game.player.v1" 解析为 {game.player, 1}。

func (Ref) String

func (r Ref) String() string

String 实现 fmt.Stringer。

func (Ref) Validate

func (r Ref) Validate() error

Validate 校验 id 形态:≥2 段、每段合法、不含版本段、非 gt. 保留前缀、version>=1(§8.6 id-format)。

func (Ref) Wire

func (r Ref) Wire() string

Wire 返回线上串形态,如 "game.player.v1"。

type Reference

type Reference struct {
	Schema  string `yaml:"schema"`
	Version int    `yaml:"version,omitempty"` // 省略 = 同插件声明的最高 major
	Field   string `yaml:"field"`
}

Reference 是声明期完整性约束(非解码期外键,§8.4)。 指向同插件作用域内的某个 schema 字段。

type Schema

type Schema struct {
	Ref         Ref               `yaml:",inline"`
	Revision    int               `yaml:"revision,omitempty"`
	Name        string            `yaml:"name,omitempty"`
	Description string            `yaml:"description,omitempty"`
	Fields      map[string]*Field `yaml:"fields,omitempty"`
	Strict      *bool             `yaml:"strict,omitempty"`
	Deprecated  bool              `yaml:"deprecated,omitempty"`
	ReplacedBy  *Ref              `yaml:"replaced_by,omitempty"`

	// IndexableFields 是 v1 遗留的 indexable_fields 声明(AGENTS.md 最小 manifest),
	// 加载时升格为对应 Field 的 Queryable + Alias。
	IndexableFields []IndexableField `yaml:"indexable_fields,omitempty"`
}

Schema 是一个 schema 声明(§8.2)。根必须是 object。

func (*Schema) Validate

func (s *Schema) Validate(known map[string]*Schema) []Issue

Validate 校验 schema 声明合法性,known 为同插件作用域内的 schema 集合(按 id 索引,取最高 major)。 返回所有发现的问题,空切片表示合法。

func (*Schema) ValidateValue

func (s *Schema) ValidateValue(v event.Value) []Issue

ValidateValue 在解码期校验一个 payload(event.Value,根必须是 object)是否符合本 schema 声明。 这是 P1 闭环的核心:plugin.verify 据此报出 payload 与 schema 不符。

覆盖 §8.6:payload-conforms / root-must-be-object / unknown-field / int-range-overflow / uint-range-overflow / float-representability / enum-unknown-value / enum-open-unknown-value。

type Semantic

type Semantic string

Semantic is a field's semantic annotation (§8.3).

Allowed values:

  • builtin: a member of the platform-closed vocabulary (see builtinSemantics, codegen'd from contract/specs/schema.yaml).
  • x- prefix: an experimental semantic. Must carry governance metadata; the checker enforces that x- semantics are never queryable/aggregatable/groupable.
  • opaque: explicitly "no semantic".

Any semantic starting with "gt." is a platform-reserved namespace that plugins must never define (gt.reserved-namespace).

func (Semantic) AllowedKinds

func (s Semantic) AllowedKinds() []event.ValueKind

AllowedKinds returns the wire ValueKinds permitted for this builtin semantic, derived from its allowed declared types. Non-builtin semantics return nil.

func (Semantic) IsBuiltin

func (s Semantic) IsBuiltin() bool

IsBuiltin reports whether the semantic is in the platform-closed set.

func (Semantic) IsExperimental

func (s Semantic) IsExperimental() bool

IsExperimental reports whether the semantic is an experimental "x-" term.

func (Semantic) IsReserved

func (s Semantic) IsReserved() bool

IsReserved reports whether the semantic attempts to occupy the reserved "gt." platform namespace.

type Type

type Type string

Type is a declared schema type. It is the plugin-author-facing type name; at the wire it always collapses to one of the nine event.ValueKind values (see WireKind). Declaring a wide type only affects range validation, storage column choice, UI rendering and aggregation-overflow judgement — it does not add a new wire kind.

const (
	TypeInt8    Type = "int8"
	TypeInt16   Type = "int16"
	TypeInt32   Type = "int32"
	TypeInt64   Type = "int64"
	TypeUint8   Type = "uint8"
	TypeUint16  Type = "uint16"
	TypeUint32  Type = "uint32"
	TypeUint64  Type = "uint64"
	TypeFloat32 Type = "float32"
	TypeFloat64 Type = "float64"
	TypeBool    Type = "bool"
	TypeString  Type = "string"
	TypeBytes   Type = "bytes"
	TypeArray   Type = "array"
	TypeObject  Type = "object"
	TypeNull    Type = "null"
)

func ParseType

func ParseType(s string) (Type, error)

ParseType validates and converts a string into a Type.

func (Type) IntBounds

func (t Type) IntBounds() (min, max int64, ok bool)

IntBounds returns the inclusive [min,max] for signed integer types.

func (Type) IsFloat

func (t Type) IsFloat() bool

IsFloat reports whether the type is floating point.

func (Type) IsInteger

func (t Type) IsInteger() bool

IsInteger reports whether the type is a signed integer.

func (Type) IsNumeric

func (t Type) IsNumeric() bool

IsNumeric reports whether the type is any numeric kind.

func (Type) IsSigned

func (t Type) IsSigned() bool

IsSigned is an alias for IsInteger (signed integer).

func (Type) IsUnsigned

func (t Type) IsUnsigned() bool

IsUnsigned reports whether the type is an unsigned integer.

func (Type) IsValid

func (t Type) IsValid() bool

IsValid reports whether t is a legal declared type.

func (Type) UintBounds

func (t Type) UintBounds() (max uint64, ok bool)

UintBounds returns the inclusive [0,max] for unsigned integer types.

func (Type) WireKind

func (t Type) WireKind() (event.ValueKind, bool)

WireKind returns the wire ValueKind this declared type collapses to, and whether t is a known type. Unknown types yield (event.Null, false).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL