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
- func IsBuiltinSemantic(s Semantic) bool
- type Change
- type Entity
- type EnumLiteral
- type Field
- type IndexableField
- type Issue
- type KeySpec
- type Ref
- type Reference
- type Schema
- type Semantic
- type Type
- func (t Type) IntBounds() (min, max int64, ok bool)
- func (t Type) IsFloat() bool
- func (t Type) IsInteger() bool
- func (t Type) IsNumeric() bool
- func (t Type) IsSigned() bool
- func (t Type) IsUnsigned() bool
- func (t Type) IsValid() bool
- func (t Type) UintBounds() (max uint64, ok bool)
- func (t Type) WireKind() (event.ValueKind, bool)
Constants ¶
const ( // SeverityError 表示契约违反(应阻断)。 SeverityError = "error" // SeverityWarn 表示诊断/软降级。 SeverityWarn = "warn" )
Variables ¶
This section is empty.
Functions ¶
func IsBuiltinSemantic ¶
IsBuiltinSemantic reports whether s is a platform-closed semantic.
Types ¶
type Change ¶
Change describes a single field-level difference between two same-id schemas. Kind corresponds to a key in evolutionCompatibility.
type Entity ¶
type Entity struct {
Type string `yaml:"type"`
}
Entity 描述语义层的实体类型(领域自定,非平台枚举)。 仅当 semantic 为 entity_id / entity_name 时允许出现。
type EnumLiteral ¶
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 ¶
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 ¶
Ref 标识一个 schema 的 (id, version) 对(§8.2)。 id 不带版本(如 game.player),version 是 major(如 1)。 线上形态为 id + ".v" + version(如 game.player.v1),由 Wire() 生成、ParseRef 解析。
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 ¶
Validate 校验 schema 声明合法性,known 为同插件作用域内的 schema 集合(按 id 索引,取最高 major)。 返回所有发现的问题,空切片表示合法。
func (*Schema) ValidateValue ¶
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 ¶
AllowedKinds returns the wire ValueKinds permitted for this builtin semantic, derived from its allowed declared types. Non-builtin semantics return nil.
func (Semantic) IsExperimental ¶
IsExperimental reports whether the semantic is an experimental "x-" term.
func (Semantic) IsReserved ¶
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 (Type) IsUnsigned ¶
IsUnsigned reports whether the type is an unsigned integer.
func (Type) UintBounds ¶
UintBounds returns the inclusive [0,max] for unsigned integer types.